* doc/as.texinfo: Updated for -MD option.
[external/binutils.git] / gas / doc / as.texinfo
1 \input texinfo @c                               -*-Texinfo-*-
2 @c  Copyright (c) 1991, 92, 93, 94, 95, 96, 1997 Free Software Foundation, Inc.
3 @c UPDATE!!  On future updates--
4 @c   (1)   check for new machine-dep cmdline options in
5 @c         md_parse_option definitions in config/tc-*.c
6 @c   (2)   for platform-specific directives, examine md_pseudo_op
7 @c         in config/tc-*.c
8 @c   (3)   for object-format specific directives, examine obj_pseudo_op
9 @c         in config/obj-*.c       
10 @c   (4)   portable directives in potable[] in read.c
11 @c %**start of header
12 @setfilename as.info
13 @c ---config---
14 @c defaults, config file may override:
15 @set have-stabs
16 @c ---
17 @include asconfig.texi
18 @c ---
19 @c common OR combinations of conditions
20 @ifset AOUT
21 @set aout-bout
22 @end ifset
23 @ifset BOUT
24 @set aout-bout
25 @end ifset
26 @ifset H8/300
27 @set H8
28 @end ifset
29 @ifset H8/500
30 @set H8
31 @end ifset
32 @ifset SH
33 @set H8
34 @end ifset
35 @ifset HPPA
36 @set abnormal-separator
37 @end ifset
38 @c ------------
39 @ifset GENERIC
40 @settitle Using @value{AS}
41 @end ifset
42 @ifclear GENERIC
43 @settitle Using @value{AS} (@value{TARGET})
44 @end ifclear
45 @setchapternewpage odd
46 @c %**end of header
47
48 @c @smallbook
49 @c @set SMALL
50 @c WARE! Some of the machine-dependent sections contain tables of machine
51 @c instructions.  Except in multi-column format, these tables look silly.
52 @c Unfortunately, Texinfo doesn't have a general-purpose multi-col format, so
53 @c the multi-col format is faked within @example sections.
54 @c 
55 @c Again unfortunately, the natural size that fits on a page, for these tables,
56 @c is different depending on whether or not smallbook is turned on.
57 @c This matters, because of order: text flow switches columns at each page
58 @c break.
59 @c 
60 @c The format faked in this source works reasonably well for smallbook,
61 @c not well for the default large-page format.  This manual expects that if you
62 @c turn on @smallbook, you will also uncomment the "@set SMALL" to enable the
63 @c tables in question.  You can turn on one without the other at your
64 @c discretion, of course. 
65 @ifinfo
66 @set SMALL
67 @c the insn tables look just as silly in info files regardless of smallbook,
68 @c might as well show 'em anyways.
69 @end ifinfo
70
71 @ifinfo
72 @format
73 START-INFO-DIR-ENTRY
74 * As: (as).                     The GNU assembler.
75 END-INFO-DIR-ENTRY
76 @end format
77 @end ifinfo
78
79 @finalout
80 @syncodeindex ky cp
81
82 @ifinfo
83 This file documents the GNU Assembler "@value{AS}".
84
85 Copyright (C) 1991, 92, 93, 94, 95, 96, 1997 Free Software Foundation, Inc.
86
87 Permission is granted to make and distribute verbatim copies of
88 this manual provided the copyright notice and this permission notice
89 are preserved on all copies.
90
91 @ignore
92 Permission is granted to process this file through Tex and print the
93 results, provided the printed document carries copying permission
94 notice identical to this one except for the removal of this paragraph
95 (this paragraph not being relevant to the printed manual).
96
97 @end ignore
98 Permission is granted to copy and distribute modified versions of this manual
99 under the conditions for verbatim copying, provided that the entire resulting
100 derived work is distributed under the terms of a permission notice identical to
101 this one.
102
103 Permission is granted to copy and distribute translations of this manual
104 into another language, under the above conditions for modified versions.
105 @end ifinfo
106
107 @titlepage
108 @title Using @value{AS}
109 @subtitle The @sc{gnu} Assembler
110 @ifclear GENERIC
111 @subtitle for the @value{TARGET} family
112 @end ifclear
113 @sp 1
114 @subtitle January 1994
115 @sp 1
116 @sp 13
117 The Free Software Foundation Inc.  thanks The Nice Computer
118 Company of Australia for loaning Dean Elsner to write the
119 first (Vax) version of @code{as} for Project @sc{gnu}.
120 The proprietors, management and staff of TNCCA thank FSF for
121 distracting the boss while they got some work
122 done.
123 @sp 3
124 @author Dean Elsner, Jay Fenlason & friends
125 @page
126 @tex
127 {\parskip=0pt
128 \hfill {\it Using {\tt @value{AS}}}\par
129 \hfill Edited by Cygnus Support\par
130 }
131 %"boxit" macro for figures:
132 %Modified from Knuth's ``boxit'' macro from TeXbook (answer to exercise 21.3)
133 \gdef\boxit#1#2{\vbox{\hrule\hbox{\vrule\kern3pt
134      \vbox{\parindent=0pt\parskip=0pt\hsize=#1\kern3pt\strut\hfil
135 #2\hfil\strut\kern3pt}\kern3pt\vrule}\hrule}}%box with visible outline
136 \gdef\ibox#1#2{\hbox to #1{#2\hfil}\kern8pt}% invisible box
137 @end tex
138
139 @vskip 0pt plus 1filll
140 Copyright @copyright{} 1991, 92, 93, 94, 95, 96, 1997 Free Software Foundation, Inc.
141
142 Permission is granted to make and distribute verbatim copies of
143 this manual provided the copyright notice and this permission notice
144 are preserved on all copies.
145
146 Permission is granted to copy and distribute modified versions of this manual
147 under the conditions for verbatim copying, provided that the entire resulting
148 derived work is distributed under the terms of a permission notice identical to
149 this one.
150
151 Permission is granted to copy and distribute translations of this manual
152 into another language, under the above conditions for modified versions.
153 @end titlepage
154
155 @ifinfo
156 @node Top
157 @top Using @value{AS}
158
159 This file is a user guide to the @sc{gnu} assembler @code{@value{AS}}.
160 @ifclear GENERIC
161 This version of the file describes @code{@value{AS}} configured to generate
162 code for @value{TARGET} architectures.
163 @end ifclear
164 @menu
165 * Overview::                    Overview
166 * Invoking::                    Command-Line Options
167 * Syntax::                      Syntax
168 * Sections::                    Sections and Relocation
169 * Symbols::                     Symbols
170 * Expressions::                 Expressions
171 * Pseudo Ops::                  Assembler Directives
172 * Machine Dependencies::        Machine Dependent Features
173 * Reporting Bugs::              Reporting Bugs
174 * Acknowledgements::            Who Did What
175 * Index::                       Index
176 @end menu
177 @end ifinfo
178
179 @node Overview
180 @chapter Overview
181 @iftex
182 This manual is a user guide to the @sc{gnu} assembler @code{@value{AS}}.
183 @ifclear GENERIC
184 This version of the manual describes @code{@value{AS}} configured to generate
185 code for @value{TARGET} architectures.
186 @end ifclear
187 @end iftex
188
189 @cindex invocation summary
190 @cindex option summary
191 @cindex summary of options
192 Here is a brief summary of how to invoke @code{@value{AS}}.  For details,
193 @pxref{Invoking,,Comand-Line Options}.
194
195 @c We don't use deffn and friends for the following because they seem
196 @c to be limited to one line for the header.
197 @smallexample
198 @value{AS} [ -a[cdhlns][=file] ] [ -D ]  [ --defsym @var{sym}=@var{val} ]
199  [ -f ] [ --help ] [ -I @var{dir} ] [ -J ] [ -K ] [ -L ]
200  [ -o @var{objfile} ] [ -R ] [ --statistics ] [ -v ] [ -version ]
201  [ --version ] [ -W ] [ -w ] [ -x ] [ -Z ]
202 @ifset A29K
203 @c am29k has no machine-dependent assembler options
204 @end ifset
205 @c start-sanitize-arc
206 @ifset ARC
207  [ -mbig-endian | -mlittle-endian ]
208 @end ifset
209 @c end-sanitize-arc
210 @ifset D10V
211  [ -O ]
212 @end ifset
213
214 @ifset H8
215 @c Hitachi family chips have no machine-dependent assembler options
216 @end ifset
217 @ifset HPPA
218 @c HPPA has no machine-dependent assembler options (yet).
219 @end ifset
220 @ifset SPARC
221 @c The order here is important.  See c-sparc.texi.
222  [ -Av6 | -Av7 | -Av8 | -Asparclet | -Asparclite | -Av9 | -Av9a ]
223  [ -xarch=v8plus | -xarch=v8plusa ] [ -bump ]
224 @end ifset
225 @ifset Z8000
226 @c Z8000 has no machine-dependent assembler options
227 @end ifset
228 @ifset I960
229 @c see md_parse_option in tc-i960.c
230  [ -ACA | -ACA_A | -ACB | -ACC | -AKA | -AKB | -AKC | -AMC ]
231  [ -b ] [ -no-relax ]
232 @end ifset
233 @ifset M680X0
234  [ -l ] [ -m68000 | -m68010 | -m68020 | ... ]
235 @end ifset
236 @ifset MIPS
237  [ -nocpp ] [ -EL ] [ -EB ] [ -G @var{num} ] [ -mcpu=@var{CPU} ]
238  [ -mips1 ] [ -mips2 ] [ -mips3 ] [ -m4650 ] [ -no-m4650 ]
239  [ --trap ] [ --break ]
240  [ --emulation=@var{name} ]
241 @end ifset
242  [ -- | @var{files} @dots{} ]
243 @end smallexample
244
245 @table @code
246 @item -a[dhlns]
247 Turn on listings, in any of a variety of ways:
248
249 @table @code
250 @item -ad
251 omit debugging directives
252
253 @item -ah
254 include high-level source
255
256 @item -al
257 include assembly
258
259 @item -an
260 omit forms processing
261
262 @item -as
263 include symbols
264
265 @item =file
266 set the name of the listing file
267 @end table
268
269 You may combine these options; for example, use @samp{-aln} for assembly
270 listing without forms processing.  The @samp{=file} option, if used, must be
271 the last one.  By itself, @samp{-a} defaults to @samp{-ahls}---that is, all
272 listings turned on.
273
274 @item -D
275 Ignored.  This option is accepted for script compatibility with calls to
276 other assemblers.
277
278 @item --defsym @var{sym}=@var{value}
279 Define the symbol @var{sym} to be @var{value} before assembling the input file.
280 @var{value} must be an integer constant.  As in C, a leading @samp{0x}
281 indicates a hexadecimal value, and a leading @samp{0} indicates an octal value.
282
283 @item -f
284 ``fast''---skip whitespace and comment preprocessing (assume source is
285 compiler output).
286
287 @item --help
288 Print a summary of the command line options and exit.
289
290 @item -I @var{dir}
291 Add directory @var{dir} to the search list for @code{.include} directives.
292
293 @item -J
294 Don't warn about signed overflow.
295
296 @item -K
297 @ifclear DIFF-TBL-KLUGE
298 This option is accepted but has no effect on the @value{TARGET} family.
299 @end ifclear
300 @ifset DIFF-TBL-KLUGE
301 Issue warnings when difference tables altered for long displacements.
302 @end ifset
303
304 @item -L
305 Keep (in the symbol table) local symbols, starting with @samp{L}.
306
307 @item -o @var{objfile}
308 Name the object-file output from @code{@value{AS}} @var{objfile}.
309
310 @item -R
311 Fold the data section into the text section.
312
313 @item --statistics
314 Print the maximum space (in bytes) and total time (in seconds) used by
315 assembly.
316
317 @item -v
318 @itemx -version
319 Print the @code{as} version.
320
321 @item --version
322 Print the @code{as} version and exit.
323
324 @item -W
325 Suppress warning messages.
326
327 @item -w
328 Ignored.
329
330 @item -x
331 Ignored.
332
333 @item -Z
334 Generate an object file even after errors.
335
336 @item -- | @var{files} @dots{}
337 Standard input, or source files to assemble.
338
339 @end table
340
341 @ifset ARC
342 The following options are available when @value{AS} is configured for
343 an ARC processor.
344
345 @table @code
346
347 @cindex ARC endianness
348 @cindex endianness, ARC
349 @cindex big endian output, ARC
350 @item -mbig-endian
351 Generate ``big endian'' format output.
352
353 @cindex little endian output, ARC
354 @item -mlittle-endian
355 Generate ``little endian'' format output.
356
357 @end table
358 @end ifset
359
360 @ifset D10V
361 The following options are available when @value{AS} is configured for
362 a D10V processor.
363 @table @code
364 @cindex D10V optimization
365 @cindex optimization, D10V
366 @item -O
367 Optimize output by parallelizing instructions.
368 @end table
369 @end ifset
370
371 @ifset I960
372 The following options are available when @value{AS} is configured for the
373 Intel 80960 processor.
374
375 @table @code
376 @item -ACA | -ACA_A | -ACB | -ACC | -AKA | -AKB | -AKC | -AMC
377 Specify which variant of the 960 architecture is the target.
378
379 @item -b
380 Add code to collect statistics about branches taken.
381
382 @item -no-relax
383 Do not alter compare-and-branch instructions for long displacements;
384 error if necessary.
385
386 @end table
387 @end ifset
388
389 @ifset M680X0
390 The following options are available when @value{AS} is configured for the
391 Motorola 68000 series.
392
393 @table @code
394
395 @item -l
396 Shorten references to undefined symbols, to one word instead of two.
397
398 @item -m68000 | -m68008 | -m68010 | -m68020 | -m68030 | -m68040 | -m68060
399 @itemx | -m68302 | -m68331 | -m68332 | -m68333 | -m68340 | -mcpu32 | -m5200
400 Specify what processor in the 68000 family is the target.  The default
401 is normally the 68020, but this can be changed at configuration time.
402
403 @item -m68881 | -m68882 | -mno-68881 | -mno-68882
404 The target machine does (or does not) have a floating-point coprocessor.
405 The default is to assume a coprocessor for 68020, 68030, and cpu32.  Although
406 the basic 68000 is not compatible with the 68881, a combination of the
407 two can be specified, since it's possible to do emulation of the
408 coprocessor instructions with the main processor.
409
410 @item -m68851 | -mno-68851
411 The target machine does (or does not) have a memory-management
412 unit coprocessor.  The default is to assume an MMU for 68020 and up.
413
414 @end table
415 @end ifset
416
417 @ifset SPARC
418 The following options are available when @code{@value{AS}} is configured
419 for the SPARC architecture:
420
421 @table @code
422 @item -Av6 | -Av7 | -Av8 | -Asparclet | -Asparclite | -Av9 | -Av9a
423 Explicitly select a variant of the SPARC architecture.
424
425 @item -xarch=v8plus | -xarch=v8plusa
426 For compatibility with the Solaris v9 assembler.  These options are
427 equivalent to -Av9 and -Av9a, respectively.
428
429 @item -bump
430 Warn when the assembler switches to another architecture.
431 @end table
432 @end ifset
433
434 @ifset MIPS
435 The following options are available when @value{AS} is configured for
436 a MIPS processor.
437
438 @table @code
439 @item -G @var{num}
440 This option sets the largest size of an object that can be referenced
441 implicitly with the @code{gp} register.  It is only accepted for targets that
442 use ECOFF format, such as a DECstation running Ultrix.  The default value is 8.
443
444 @cindex MIPS endianness
445 @cindex endianness, MIPS
446 @cindex big endian output, MIPS
447 @item -EB
448 Generate ``big endian'' format output.
449
450 @cindex little endian output, MIPS
451 @item -EL
452 Generate ``little endian'' format output.
453
454 @cindex MIPS ISA
455 @item -mips1
456 @itemx -mips2
457 @itemx -mips3
458 Generate code for a particular MIPS Instruction Set Architecture level.
459 @samp{-mips1} corresponds to the @sc{r2000} and @sc{r3000} processors,
460 @samp{-mips2} to the @sc{r6000} processor, and @samp{-mips3} to the @sc{r4000}
461 processor.
462
463 @item -m4650
464 @item -no-m4650
465 Generate code for the MIPS @sc{r4650} chip.  This tells the assembler to accept
466 the @samp{mad} and @samp{madu} instruction, and to not schedule @samp{nop}
467 instructions around accesses to the @samp{HI} and @samp{LO} registers.
468 @samp{-no-m4650} turns off this option.
469
470 @item -mcpu=@var{CPU}
471 Generate code for a particular MIPS cpu.  This has little effect on the
472 assembler, but it is passed by @code{@value{GCC}}.
473
474 @cindex emulation
475 @item --emulation=@var{name}
476 This option causes @code{@value{AS}} to emulated @code{@value{AS}} configured
477 for some other target, in all respects, including output format (choosing
478 between ELF and ECOFF only), handling of pseudo-opcodes which may generate
479 debugging information or store symbol table information, and default
480 endianness.  The available configuration names are: @samp{mipsecoff},
481 @samp{mipself}, @samp{mipslecoff}, @samp{mipsbecoff}, @samp{mipslelf},
482 @samp{mipsbelf}.  The first two do not alter the default endianness from that
483 of the primary target for which the assembler was configured; the others change
484 the default to little- or big-endian as indicated by the @samp{b} or @samp{l}
485 in the name.  Using @samp{-EB} or @samp{-EL} will override the endianness
486 selection in any case.
487
488 This option is currently supported only when the primary target
489 @code{@value{AS}} is configured for is a MIPS ELF or ECOFF target.
490 Furthermore, the primary target or others specified with
491 @samp{--enable-targets=@dots{}} at configuration time must include support for
492 the other format, if both are to be available.  For example, the Irix 5
493 configuration includes support for both.
494
495 Eventually, this option will support more configurations, with more
496 fine-grained control over the assembler's behavior, and will be supported for
497 more processors.
498
499 @item -nocpp
500 @code{@value{AS}} ignores this option.  It is accepted for compatibility with
501 the native tools.
502
503 @need 900
504 @item --trap
505 @itemx --no-trap
506 @itemx --break
507 @itemx --no-break
508 Control how to deal with multiplication overflow and division by zero.
509 @samp{--trap} or @samp{--no-break} (which are synonyms) take a trap exception
510 (and only work for Instruction Set Architecture level 2 and higher);
511 @samp{--break} or @samp{--no-trap} (also synonyms, and the default) take a
512 break exception.
513 @end table
514 @end ifset
515
516 @menu
517 * Manual::                      Structure of this Manual
518 * GNU Assembler::               @value{AS}, the GNU Assembler
519 * Object Formats::              Object File Formats
520 * Command Line::                Command Line
521 * Input Files::                 Input Files
522 * Object::                      Output (Object) File
523 * Errors::                      Error and Warning Messages
524 @end menu
525
526 @node Manual
527 @section Structure of this Manual
528
529 @cindex manual, structure and purpose
530 This manual is intended to describe what you need to know to use
531 @sc{gnu} @code{@value{AS}}.  We cover the syntax expected in source files, including
532 notation for symbols, constants, and expressions; the directives that
533 @code{@value{AS}} understands; and of course how to invoke @code{@value{AS}}.
534
535 @ifclear GENERIC
536 We also cover special features in the @value{TARGET}
537 configuration of @code{@value{AS}}, including assembler directives.
538 @end ifclear
539 @ifset GENERIC
540 This manual also describes some of the machine-dependent features of
541 various flavors of the assembler.
542 @end ifset
543
544 @cindex machine instructions (not covered)
545 On the other hand, this manual is @emph{not} intended as an introduction
546 to programming in assembly language---let alone programming in general!
547 In a similar vein, we make no attempt to introduce the machine
548 architecture; we do @emph{not} describe the instruction set, standard
549 mnemonics, registers or addressing modes that are standard to a
550 particular architecture.
551 @ifset GENERIC
552 You may want to consult the manufacturer's
553 machine architecture manual for this information.
554 @end ifset
555 @ifclear GENERIC
556 @ifset H8/300
557 For information on the H8/300 machine instruction set, see @cite{H8/300
558 Series Programming Manual} (Hitachi ADE--602--025).  For the H8/300H,
559 see @cite{H8/300H Series Programming Manual} (Hitachi).
560 @end ifset
561 @ifset H8/500
562 For information on the H8/500 machine instruction set, see @cite{H8/500
563 Series Programming Manual} (Hitachi M21T001).
564 @end ifset
565 @ifset SH
566 For information on the Hitachi SH machine instruction set, see
567 @cite{SH-Microcomputer User's Manual} (Hitachi Micro Systems, Inc.).
568 @end ifset
569 @ifset Z8000
570 For information on the Z8000 machine instruction set, see @cite{Z8000 CPU Technical Manual}
571 @end ifset
572 @end ifclear
573
574 @c I think this is premature---doc@cygnus.com, 17jan1991
575 @ignore
576 Throughout this manual, we assume that you are running @dfn{GNU},
577 the portable operating system from the @dfn{Free Software
578 Foundation, Inc.}.  This restricts our attention to certain kinds of
579 computer (in particular, the kinds of computers that @sc{gnu} can run on);
580 once this assumption is granted examples and definitions need less
581 qualification.
582
583 @code{@value{AS}} is part of a team of programs that turn a high-level
584 human-readable series of instructions into a low-level
585 computer-readable series of instructions.  Different versions of
586 @code{@value{AS}} are used for different kinds of computer.
587 @end ignore
588
589 @c There used to be a section "Terminology" here, which defined
590 @c "contents", "byte", "word", and "long".  Defining "word" to any
591 @c particular size is confusing when the .word directive may generate 16
592 @c bits on one machine and 32 bits on another; in general, for the user
593 @c version of this manual, none of these terms seem essential to define.
594 @c They were used very little even in the former draft of the manual;
595 @c this draft makes an effort to avoid them (except in names of
596 @c directives).
597
598 @node GNU Assembler
599 @section @value{AS}, the GNU Assembler
600
601 @sc{gnu} @code{as} is really a family of assemblers.
602 @ifclear GENERIC
603 This manual describes @code{@value{AS}}, a member of that family which is
604 configured for the @value{TARGET} architectures.
605 @end ifclear
606 If you use (or have used) the @sc{gnu} assembler on one architecture, you
607 should find a fairly similar environment when you use it on another
608 architecture.  Each version has much in common with the others,
609 including object file formats, most assembler directives (often called
610 @dfn{pseudo-ops}) and assembler syntax.@refill
611
612 @cindex purpose of @sc{gnu} @code{@value{AS}}
613 @code{@value{AS}} is primarily intended to assemble the output of the
614 @sc{gnu} C compiler @code{@value{GCC}} for use by the linker
615 @code{@value{LD}}.  Nevertheless, we've tried to make @code{@value{AS}}
616 assemble correctly everything that other assemblers for the same
617 machine would assemble.
618 @ifset VAX
619 Any exceptions are documented explicitly (@pxref{Machine Dependencies}).
620 @end ifset
621 @ifset M680X0
622 @c This remark should appear in generic version of manual; assumption
623 @c here is that generic version sets M680x0.
624 This doesn't mean @code{@value{AS}} always uses the same syntax as another
625 assembler for the same architecture; for example, we know of several
626 incompatible versions of 680x0 assembly language syntax.
627 @end ifset
628
629 Unlike older assemblers, @code{@value{AS}} is designed to assemble a source
630 program in one pass of the source file.  This has a subtle impact on the
631 @kbd{.org} directive (@pxref{Org,,@code{.org}}).
632
633 @node Object Formats
634 @section Object File Formats
635
636 @cindex object file format
637 The @sc{gnu} assembler can be configured to produce several alternative
638 object file formats.  For the most part, this does not affect how you
639 write assembly language programs; but directives for debugging symbols
640 are typically different in different file formats.  @xref{Symbol
641 Attributes,,Symbol Attributes}.
642 @ifclear GENERIC
643 @ifclear MULTI-OBJ
644 On the @value{TARGET}, @code{@value{AS}} is configured to produce
645 @value{OBJ-NAME} format object files.
646 @end ifclear
647 @c The following should exhaust all configs that set MULTI-OBJ, ideally
648 @ifset A29K
649 On the @value{TARGET}, @code{@value{AS}} can be configured to produce either
650 @code{a.out} or COFF format object files.
651 @end ifset
652 @ifset I960
653 On the @value{TARGET}, @code{@value{AS}} can be configured to produce either
654 @code{b.out} or COFF format object files.
655 @end ifset
656 @ifset HPPA
657 On the @value{TARGET}, @code{@value{AS}} can be configured to produce either
658 SOM or ELF format object files.
659 @end ifset
660 @end ifclear
661
662 @node Command Line
663 @section Command Line
664
665 @cindex command line conventions
666 After the program name @code{@value{AS}}, the command line may contain
667 options and file names.  Options may appear in any order, and may be
668 before, after, or between file names.  The order of file names is
669 significant.
670
671 @cindex standard input, as input file
672 @kindex --
673 @file{--} (two hyphens) by itself names the standard input file
674 explicitly, as one of the files for @code{@value{AS}} to assemble.
675
676 @cindex options, command line
677 Except for @samp{--} any command line argument that begins with a
678 hyphen (@samp{-}) is an option.  Each option changes the behavior of
679 @code{@value{AS}}.  No option changes the way another option works.  An
680 option is a @samp{-} followed by one or more letters; the case of
681 the letter is important.   All options are optional.
682
683 Some options expect exactly one file name to follow them.  The file
684 name may either immediately follow the option's letter (compatible
685 with older assemblers) or it may be the next command argument (@sc{gnu}
686 standard).  These two command lines are equivalent:
687
688 @smallexample
689 @value{AS} -o my-object-file.o mumble.s
690 @value{AS} -omy-object-file.o mumble.s
691 @end smallexample
692
693 @node Input Files
694 @section Input Files
695
696 @cindex input
697 @cindex source program
698 @cindex files, input
699 We use the phrase @dfn{source program}, abbreviated @dfn{source}, to
700 describe the program input to one run of @code{@value{AS}}.  The program may
701 be in one or more files; how the source is partitioned into files
702 doesn't change the meaning of the source.
703
704 @c I added "con" prefix to "catenation" just to prove I can overcome my
705 @c APL training...   doc@cygnus.com
706 The source program is a concatenation of the text in all the files, in the
707 order specified.
708
709 Each time you run @code{@value{AS}} it assembles exactly one source
710 program.  The source program is made up of one or more files.
711 (The standard input is also a file.)
712
713 You give @code{@value{AS}} a command line that has zero or more input file
714 names.  The input files are read (from left file name to right).  A
715 command line argument (in any position) that has no special meaning
716 is taken to be an input file name.
717
718 If you give @code{@value{AS}} no file names it attempts to read one input file
719 from the @code{@value{AS}} standard input, which is normally your terminal.  You
720 may have to type @key{ctl-D} to tell @code{@value{AS}} there is no more program
721 to assemble.
722
723 Use @samp{--} if you need to explicitly name the standard input file
724 in your command line.
725
726 If the source is empty, @code{@value{AS}} produces a small, empty object
727 file.
728
729 @subheading Filenames and Line-numbers
730
731 @cindex input file linenumbers
732 @cindex line numbers, in input files
733 There are two ways of locating a line in the input file (or files) and
734 either may be used in reporting error messages.  One way refers to a line
735 number in a physical file; the other refers to a line number in a
736 ``logical'' file.  @xref{Errors, ,Error and Warning Messages}.
737
738 @dfn{Physical files} are those files named in the command line given
739 to @code{@value{AS}}.
740
741 @dfn{Logical files} are simply names declared explicitly by assembler
742 directives; they bear no relation to physical files.  Logical file names
743 help error messages reflect the original source file, when @code{@value{AS}}
744 source is itself synthesized from other files.
745 @xref{App-File,,@code{.app-file}}.
746
747 @node Object
748 @section Output (Object) File
749
750 @cindex object file
751 @cindex output file
752 @kindex a.out
753 @kindex .o
754 Every time you run @code{@value{AS}} it produces an output file, which is
755 your assembly language program translated into numbers.  This file
756 is the object file.  Its default name is
757 @ifclear BOUT
758 @code{a.out}.
759 @end ifclear
760 @ifset BOUT
761 @ifset GENERIC
762 @code{a.out}, or 
763 @end ifset
764 @code{b.out} when @code{@value{AS}} is configured for the Intel 80960.
765 @end ifset
766 You can give it another name by using the @code{-o} option.  Conventionally,
767 object file names end with @file{.o}.  The default name is used for historical
768 reasons: older assemblers were capable of assembling self-contained programs
769 directly into a runnable program.  (For some formats, this isn't currently
770 possible, but it can be done for the @code{a.out} format.)
771
772 @cindex linker
773 @kindex ld
774 The object file is meant for input to the linker @code{@value{LD}}.  It contains
775 assembled program code, information to help @code{@value{LD}} integrate
776 the assembled program into a runnable file, and (optionally) symbolic
777 information for the debugger.
778
779 @c link above to some info file(s) like the description of a.out.
780 @c don't forget to describe @sc{gnu} info as well as Unix lossage.
781
782 @node Errors
783 @section Error and Warning Messages
784
785 @cindex error messsages
786 @cindex warning messages
787 @cindex messages from @code{@value{AS}}
788 @code{@value{AS}} may write warnings and error messages to the standard error
789 file (usually your terminal).  This should not happen when  a compiler
790 runs @code{@value{AS}} automatically.  Warnings report an assumption made so
791 that @code{@value{AS}} could keep assembling a flawed program; errors report a
792 grave problem that stops the assembly.
793
794 @cindex format of warning messages
795 Warning messages have the format
796
797 @smallexample
798 file_name:@b{NNN}:Warning Message Text
799 @end smallexample
800
801 @noindent
802 @cindex line numbers, in warnings/errors
803 (where @b{NNN} is a line number).  If a logical file name has been given
804 (@pxref{App-File,,@code{.app-file}}) it is used for the filename,
805 otherwise the name of the current input file is used.  If a logical line
806 number was given
807 @ifset GENERIC
808 (@pxref{Line,,@code{.line}})
809 @end ifset
810 @ifclear GENERIC
811 @ifclear A29K
812 (@pxref{Line,,@code{.line}})
813 @end ifclear
814 @ifset A29K
815 (@pxref{Ln,,@code{.ln}})
816 @end ifset
817 @end ifclear
818 then it is used to calculate the number printed,
819 otherwise the actual line in the current source file is printed.  The
820 message text is intended to be self explanatory (in the grand Unix
821 tradition).
822
823 @cindex format of error messages
824 Error messages have the format
825 @smallexample
826 file_name:@b{NNN}:FATAL:Error Message Text
827 @end smallexample
828 The file name and line number are derived as for warning
829 messages.  The actual message text may be rather less explanatory
830 because many of them aren't supposed to happen.
831
832 @node Invoking
833 @chapter Command-Line Options
834
835 @cindex options, all versions of @code{@value{AS}}
836 This chapter describes command-line options available in @emph{all}
837 versions of the @sc{gnu} assembler; @pxref{Machine Dependencies}, for options specific
838 @ifclear GENERIC
839 to the @value{TARGET}.
840 @end ifclear
841 @ifset GENERIC
842 to particular machine architectures.
843 @end ifset
844
845 If you are invoking @code{@value{AS}} via the @sc{gnu} C compiler (version 2), you
846 can use the @samp{-Wa} option to pass arguments through to the
847 assembler.  The assembler arguments must be separated from each other
848 (and the @samp{-Wa}) by commas.  For example:
849
850 @smallexample
851 gcc -c -g -O -Wa,-alh,-L file.c
852 @end smallexample
853
854 @noindent
855 emits a listing to standard output with high-level
856 and assembly source.
857
858 Usually you do not need to use this @samp{-Wa} mechanism, since many compiler
859 command-line options are automatically passed to the assembler by the compiler.
860 (You can call the @sc{gnu} compiler driver with the @samp{-v} option to see
861 precisely what options it passes to each compilation pass, including the
862 assembler.)
863
864 @menu
865 * a::             -a[cdhlns] enable listings
866 * D::             -D for compatibility
867 * f::             -f to work faster
868 * I::             -I for .include search path
869 @ifclear DIFF-TBL-KLUGE
870 * K::             -K for compatibility
871 @end ifclear
872 @ifset DIFF-TBL-KLUGE
873 * K::             -K for difference tables
874 @end ifset
875
876 * L::             -L to retain local labels
877 * M::             -M or --mri to assemble in MRI compatibility mode
878 * MD::            --MD for dependency tracking
879 * o::             -o to name the object file
880 * R::             -R to join data and text sections
881 * statistics::    --statistics to see statistics about assembly
882 * v::             -v to announce version
883 * W::             -W to suppress warnings
884 * Z::             -Z to make object file even after errors
885 @end menu
886
887 @node a
888 @section Enable Listings: @code{-a[cdhlns]}
889
890 @kindex -a
891 @kindex -ac
892 @kindex -ad
893 @kindex -ah
894 @kindex -al
895 @kindex -an
896 @kindex -as
897 @cindex listings, enabling
898 @cindex assembly listings, enabling
899
900 These options enable listing output from the assembler.  By itself,
901 @samp{-a} requests high-level, assembly, and symbols listing.
902 You can use other letters to select specific options for the list:
903 @samp{-ah} requests a high-level language listing,
904 @samp{-al} requests an output-program assembly listing, and
905 @samp{-as} requests a symbol table listing.
906 High-level listings require that a compiler debugging option like
907 @samp{-g} be used, and that assembly listings (@samp{-al}) be requested
908 also.
909
910 Use the @samp{-ac} option to omit false conditionals from a listing.  Any lines
911 which are not assembled because of a false @code{.if} (or @code{.ifdef}, or any
912 other conditional), or a true @code{.if} followed by an @code{.else}, will be
913 omitted from the listing.
914
915 Use the @samp{-ad} option to omit debugging directives from the
916 listing.
917
918 Once you have specified one of these options, you can further control
919 listing output and its appearance using the directives @code{.list},
920 @code{.nolist}, @code{.psize}, @code{.eject}, @code{.title}, and
921 @code{.sbttl}.
922 The @samp{-an} option turns off all forms processing.
923 If you do not request listing output with one of the @samp{-a} options, the
924 listing-control directives have no effect.
925
926 The letters after @samp{-a} may be combined into one option,
927 @emph{e.g.}, @samp{-aln}.
928
929 @node D
930 @section @code{-D}
931
932 @kindex -D
933 This option has no effect whatsoever, but it is accepted to make it more
934 likely that scripts written for other assemblers also work with
935 @code{@value{AS}}.
936
937 @node f
938 @section Work Faster: @code{-f}
939
940 @kindex -f
941 @cindex trusted compiler
942 @cindex faster processing (@code{-f})
943 @samp{-f} should only be used when assembling programs written by a
944 (trusted) compiler.  @samp{-f} stops the assembler from doing whitespace
945 and comment preprocessing on
946 the input file(s) before assembling them.  @xref{Preprocessing,
947 ,Preprocessing}.
948
949 @quotation
950 @emph{Warning:} if you use @samp{-f} when the files actually need to be
951 preprocessed (if they contain comments, for example), @code{@value{AS}} does
952 not work correctly.
953 @end quotation
954
955 @node I
956 @section @code{.include} search path: @code{-I} @var{path}
957
958 @kindex -I @var{path}
959 @cindex paths for @code{.include}
960 @cindex search path for @code{.include}
961 @cindex @code{include} directive search path
962 Use this option to add a @var{path} to the list of directories
963 @code{@value{AS}} searches for files specified in @code{.include}
964 directives (@pxref{Include,,@code{.include}}).  You may use @code{-I} as
965 many times as necessary to include a variety of paths.  The current
966 working directory is always searched first; after that, @code{@value{AS}}
967 searches any @samp{-I} directories in the same order as they were
968 specified (left to right) on the command line.
969
970 @node K
971 @section Difference Tables: @code{-K}
972
973 @kindex -K
974 @ifclear DIFF-TBL-KLUGE
975 On the @value{TARGET} family, this option is allowed, but has no effect.  It is
976 permitted for compatibility with the @sc{gnu} assembler on other platforms,
977 where it can be used to warn when the assembler alters the machine code
978 generated for @samp{.word} directives in difference tables.  The @value{TARGET}
979 family does not have the addressing limitations that sometimes lead to this
980 alteration on other platforms.
981 @end ifclear
982
983 @ifset DIFF-TBL-KLUGE
984 @cindex difference tables, warning
985 @cindex warning for altered difference tables
986 @code{@value{AS}} sometimes alters the code emitted for directives of the form
987 @samp{.word @var{sym1}-@var{sym2}}; @pxref{Word,,@code{.word}}.
988 You can use the @samp{-K} option if you want a warning issued when this
989 is done.
990 @end ifset
991
992 @node L
993 @section Include Local Labels: @code{-L}
994
995 @kindex -L
996 @cindex local labels, retaining in output
997 Labels beginning with @samp{L} (upper case only) are called @dfn{local
998 labels}. @xref{Symbol Names}.  Normally you do not see such labels when
999 debugging, because they are intended for the use of programs (like
1000 compilers) that compose assembler programs, not for your notice.
1001 Normally both @code{@value{AS}} and @code{@value{LD}} discard such labels, so you do not
1002 normally debug with them.
1003
1004 This option tells @code{@value{AS}} to retain those @samp{L@dots{}} symbols
1005 in the object file.  Usually if you do this you also tell the linker
1006 @code{@value{LD}} to preserve symbols whose names begin with @samp{L}.
1007
1008 By default, a local label is any label beginning with @samp{L}, but each
1009 target is allowed to redefine the local label prefix.
1010 @ifset HPPA
1011 On the HPPA local labels begin with @samp{L$}.
1012 @end ifset
1013 @c start-sanitize-arc
1014 @ifset ARC
1015 On the ARC local labels begin with @samp{.L}.
1016 @end ifset
1017 @c end-sanitize-arc
1018
1019 @node M
1020 @section Assemble in MRI Compatibility Mode: @code{-M}
1021
1022 @kindex -M
1023 @cindex MRI compatibility mode
1024 The @code{-M} or @code{--mri} option selects MRI compatibility mode.  This
1025 changes the syntax and pseudo-op handling of @code{@value{AS}} to make it
1026 compatible with the @code{ASM68K} or the @code{ASM960} (depending upon the
1027 configured target) assembler from Microtec Research.  The exact nature of the
1028 MRI syntax will not be documented here; see the MRI manuals for more
1029 information.  Note in particular that the handling of macros and macro
1030 arguments is somewhat different.  The purpose of this option is to permit
1031 assembling existing MRI assembler code using @code{@value{AS}}.
1032
1033 The MRI compatibility is not complete.  Certain operations of the MRI assembler
1034 depend upon its object file format, and can not be supported using other object
1035 file formats.  Supporting these would require enhancing each object file format
1036 individually.  These are:
1037
1038 @itemize @bullet
1039 @item global symbols in common section
1040
1041 The m68k MRI assembler supports common sections which are merged by the linker.
1042 Other object file formats do not support this.  @code{@value{AS}} handles
1043 common sections by treating them as a single common symbol.  It permits local
1044 symbols to be defined within a common section, but it can not support global
1045 symbols, since it has no way to describe them.
1046
1047 @item complex relocations
1048
1049 The MRI assemblers support relocations against a negated section address, and
1050 relocations which combine the start addresses of two or more sections.  These
1051 are not support by other object file formats.
1052
1053 @item @code{END} pseudo-op specifying start address
1054
1055 The MRI @code{END} pseudo-op permits the specification of a start address.
1056 This is not supported by other object file formats.  The start address may
1057 instead be specified using the @code{-e} option to the linker, or in a linker
1058 script.
1059
1060 @item @code{IDNT}, @code{.ident} and @code{NAME} pseudo-ops
1061
1062 The MRI @code{IDNT}, @code{.ident} and @code{NAME} pseudo-ops assign a module
1063 name to the output file.  This is not supported by other object file formats.
1064
1065 @item @code{ORG} pseudo-op
1066
1067 The m68k MRI @code{ORG} pseudo-op begins an absolute section at a given
1068 address.  This differs from the usual @code{@value{AS}} @code{.org} pseudo-op,
1069 which changes the location within the current section.  Absolute sections are
1070 not supported by other object file formats.  The address of a section may be
1071 assigned within a linker script.
1072 @end itemize
1073
1074 There are some other features of the MRI assembler which are not supported by
1075 @code{@value{AS}}, typically either because they are difficult or because they
1076 seem of little consequence.  Some of these may be supported in future releases.
1077
1078 @itemize @bullet
1079
1080 @item EBCDIC strings
1081
1082 EBCDIC strings are not supported.
1083
1084 @item packed binary coded decimal
1085
1086 Packed binary coded decimal is not supported.  This means that the @code{DC.P}
1087 and @code{DCB.P} pseudo-ops are not supported.
1088
1089 @item @code{FEQU} pseudo-op
1090
1091 The m68k @code{FEQU} pseudo-op is not supported.
1092
1093 @item @code{NOOBJ} pseudo-op
1094
1095 The m68k @code{NOOBJ} pseudo-op is not supported.
1096
1097 @item @code{OPT} branch control options
1098
1099 The m68k @code{OPT} branch control options---@code{B}, @code{BRS}, @code{BRB},
1100 @code{BRL}, and @code{BRW}---are ignored.  @code{@value{AS}} automatically
1101 relaxes all branches, whether forward or backward, to an appropriate size, so
1102 these options serve no purpose.
1103
1104 @item @code{OPT} list control options
1105
1106 The following m68k @code{OPT} list control options are ignored: @code{C},
1107 @code{CEX}, @code{CL}, @code{CRE}, @code{E}, @code{G}, @code{I}, @code{M},
1108 @code{MEX}, @code{MC}, @code{MD}, @code{X}.
1109
1110 @item other @code{OPT} options
1111
1112 The following m68k @code{OPT} options are ignored: @code{NEST}, @code{O},
1113 @code{OLD}, @code{OP}, @code{P}, @code{PCO}, @code{PCR}, @code{PCS}, @code{R}.
1114
1115 @item @code{OPT} @code{D} option is default
1116
1117 The m68k @code{OPT} @code{D} option is the default, unlike the MRI assembler.
1118 @code{OPT NOD} may be used to turn it off.
1119
1120 @item @code{XREF} pseudo-op.
1121
1122 The m68k @code{XREF} pseudo-op is ignored.
1123
1124 @item @code{.debug} pseudo-op
1125
1126 The i960 @code{.debug} pseudo-op is not supported.
1127
1128 @item @code{.extended} pseudo-op
1129
1130 The i960 @code{.extended} pseudo-op is not supported.
1131
1132 @item @code{.list} pseudo-op.
1133
1134 The various options of the i960 @code{.list} pseudo-op are not supported.
1135
1136 @item @code{.optimize} pseudo-op
1137
1138 The i960 @code{.optimize} pseudo-op is not supported.
1139
1140 @item @code{.output} pseudo-op
1141
1142 The i960 @code{.output} pseudo-op is not supported.
1143
1144 @item @code{.setreal} pseudo-op
1145
1146 The i960 @code{.setreal} pseudo-op is not supported.
1147
1148 @end itemize
1149
1150 @node MD
1151 @section Dependency tracking: @code{--MD}
1152
1153 @kindex --MD
1154 @cindex dependency tracking
1155 @cindex make rules
1156
1157 @code{@value{AS}} can generate a dependency file for the file it creates.  This
1158 file consists of a single rule suitable for @code{make} describing the
1159 dependencies of the main source file.
1160
1161 The rule is written to the file named in its argument.
1162
1163 This feature is used in the automatic updating of makefiles.
1164
1165 @node o
1166 @section Name the Object File: @code{-o}
1167
1168 @kindex -o
1169 @cindex naming object file
1170 @cindex object file name
1171 There is always one object file output when you run @code{@value{AS}}.  By
1172 default it has the name
1173 @ifset GENERIC
1174 @ifset I960
1175 @file{a.out} (or @file{b.out}, for Intel 960 targets only).
1176 @end ifset
1177 @ifclear I960
1178 @file{a.out}.
1179 @end ifclear
1180 @end ifset
1181 @ifclear GENERIC
1182 @ifset I960
1183 @file{b.out}.
1184 @end ifset
1185 @ifclear I960
1186 @file{a.out}.
1187 @end ifclear
1188 @end ifclear
1189 You use this option (which takes exactly one filename) to give the
1190 object file a different name.
1191
1192 Whatever the object file is called, @code{@value{AS}} overwrites any
1193 existing file of the same name.
1194
1195 @node R
1196 @section Join Data and Text Sections: @code{-R}
1197
1198 @kindex -R
1199 @cindex data and text sections, joining
1200 @cindex text and data sections, joining
1201 @cindex joining text and data sections
1202 @cindex merging text and data sections
1203 @code{-R} tells @code{@value{AS}} to write the object file as if all
1204 data-section data lives in the text section.  This is only done at
1205 the very last moment:  your binary data are the same, but data
1206 section parts are relocated differently.  The data section part of
1207 your object file is zero bytes long because all its bytes are
1208 appended to the text section.  (@xref{Sections,,Sections and Relocation}.)
1209
1210 When you specify @code{-R} it would be possible to generate shorter
1211 address displacements (because we do not have to cross between text and
1212 data section).  We refrain from doing this simply for compatibility with
1213 older versions of @code{@value{AS}}.  In future, @code{-R} may work this way.
1214
1215 @ifset COFF
1216 When @code{@value{AS}} is configured for COFF output,
1217 this option is only useful if you use sections named @samp{.text} and
1218 @samp{.data}.
1219 @end ifset
1220
1221 @ifset HPPA
1222 @code{-R} is not supported for any of the HPPA targets.  Using
1223 @code{-R} generates a warning from @code{@value{AS}}.
1224 @end ifset
1225
1226 @node statistics
1227 @section Display Assembly Statistics: @code{--statistics}
1228
1229 @kindex --statistics
1230 @cindex statistics, about assembly
1231 @cindex time, total for assembly
1232 @cindex space used, maximum for assembly
1233 Use @samp{--statistics} to display two statistics about the resources used by
1234 @code{@value{AS}}: the maximum amount of space allocated during the assembly
1235 (in bytes), and the total execution time taken for the assembly (in @sc{cpu}
1236 seconds).
1237
1238 @node v
1239 @section Announce Version: @code{-v}
1240
1241 @kindex -v
1242 @kindex -version
1243 @cindex @code{@value{AS}} version
1244 @cindex version of @code{@value{AS}}
1245 You can find out what version of as is running by including the
1246 option @samp{-v} (which you can also spell as @samp{-version}) on the
1247 command line.
1248
1249 @node W
1250 @section Suppress Warnings: @code{-W}
1251
1252 @kindex -W
1253 @cindex suppressing warnings
1254 @cindex warnings, suppressing
1255 @code{@value{AS}} should never give a warning or error message when
1256 assembling compiler output.  But programs written by people often
1257 cause @code{@value{AS}} to give a warning that a particular assumption was
1258 made.  All such warnings are directed to the standard error file.
1259 If you use this option, no warnings are issued.  This option only
1260 affects the warning messages: it does not change any particular of how
1261 @code{@value{AS}} assembles your file.  Errors, which stop the assembly, are
1262 still reported.
1263
1264 @node Z
1265 @section Generate Object File in Spite of Errors: @code{-Z}
1266 @cindex object file, after errors
1267 @cindex errors, continuing after
1268 After an error message, @code{@value{AS}} normally produces no output.  If for
1269 some reason you are interested in object file output even after
1270 @code{@value{AS}} gives an error message on your program, use the @samp{-Z}
1271 option.  If there are any errors, @code{@value{AS}} continues anyways, and
1272 writes an object file after a final warning message of the form @samp{@var{n}
1273 errors, @var{m} warnings, generating bad object file.}
1274
1275 @node Syntax
1276 @chapter Syntax
1277
1278 @cindex machine-independent syntax
1279 @cindex syntax, machine-independent
1280 This chapter describes the machine-independent syntax allowed in a
1281 source file.  @code{@value{AS}} syntax is similar to what many other
1282 assemblers use; it is inspired by the BSD 4.2
1283 @ifclear VAX
1284 assembler.
1285 @end ifclear
1286 @ifset VAX
1287 assembler, except that @code{@value{AS}} does not assemble Vax bit-fields.
1288 @end ifset
1289
1290 @menu
1291 * Preprocessing::              Preprocessing
1292 * Whitespace::                  Whitespace
1293 * Comments::                    Comments
1294 * Symbol Intro::                Symbols
1295 * Statements::                  Statements
1296 * Constants::                   Constants
1297 @end menu
1298
1299 @node Preprocessing
1300 @section Preprocessing
1301
1302 @cindex preprocessing
1303 The @code{@value{AS}} internal preprocessor:
1304 @itemize @bullet
1305 @cindex whitespace, removed by preprocessor
1306 @item
1307 adjusts and removes extra whitespace.  It leaves one space or tab before
1308 the keywords on a line, and turns any other whitespace on the line into
1309 a single space.
1310
1311 @cindex comments, removed by preprocessor
1312 @item
1313 removes all comments, replacing them with a single space, or an
1314 appropriate number of newlines.
1315
1316 @cindex constants, converted by preprocessor
1317 @item
1318 converts character constants into the appropriate numeric values.
1319 @end itemize
1320
1321 It does not do macro processing, include file handling, or
1322 anything else you may get from your C compiler's preprocessor.  You can
1323 do include file processing with the @code{.include} directive
1324 (@pxref{Include,,@code{.include}}).  You can use the @sc{gnu} C compiler driver
1325 to get other ``CPP'' style preprocessing, by giving the input file a
1326 @samp{.S} suffix.  @xref{Overall Options,, Options Controlling the Kind of
1327 Output, gcc.info, Using GNU CC}.
1328
1329 Excess whitespace, comments, and character constants
1330 cannot be used in the portions of the input text that are not
1331 preprocessed.
1332
1333 @cindex turning preprocessing on and off
1334 @cindex preprocessing, turning on and off
1335 @kindex #NO_APP
1336 @kindex #APP
1337 If the first line of an input file is @code{#NO_APP} or if you use the
1338 @samp{-f} option, whitespace and comments are not removed from the input file.
1339 Within an input file, you can ask for whitespace and comment removal in
1340 specific portions of the by putting a line that says @code{#APP} before the
1341 text that may contain whitespace or comments, and putting a line that says
1342 @code{#NO_APP} after this text.  This feature is mainly intend to support
1343 @code{asm} statements in compilers whose output is otherwise free of comments
1344 and whitespace.
1345
1346 @node Whitespace
1347 @section Whitespace
1348
1349 @cindex whitespace
1350 @dfn{Whitespace} is one or more blanks or tabs, in any order.
1351 Whitespace is used to separate symbols, and to make programs neater for
1352 people to read.  Unless within character constants
1353 (@pxref{Characters,,Character Constants}), any whitespace means the same
1354 as exactly one space.
1355
1356 @node Comments
1357 @section Comments
1358
1359 @cindex comments
1360 There are two ways of rendering comments to @code{@value{AS}}.  In both
1361 cases the comment is equivalent to one space.
1362
1363 Anything from @samp{/*} through the next @samp{*/} is a comment.
1364 This means you may not nest these comments.
1365
1366 @smallexample
1367 /*
1368   The only way to include a newline ('\n') in a comment
1369   is to use this sort of comment.
1370 */
1371
1372 /* This sort of comment does not nest. */
1373 @end smallexample
1374
1375 @cindex line comment character
1376 Anything from the @dfn{line comment} character to the next newline
1377 is considered a comment and is ignored.  The line comment character is
1378 @ifset A29K
1379 @samp{;} for the AMD 29K family;
1380 @end ifset
1381 @c start-sanitize-arc
1382 @ifset ARC
1383 @samp{;} on the ARC;
1384 @end ifset
1385 @c end-sanitize-arc
1386 @ifset H8/300
1387 @samp{;} for the H8/300 family;
1388 @end ifset
1389 @ifset H8/500
1390 @samp{!} for the H8/500 family;
1391 @end ifset
1392 @ifset HPPA
1393 @samp{;} for the HPPA;
1394 @end ifset
1395 @ifset I960
1396 @samp{#} on the i960;
1397 @end ifset
1398 @ifset SH
1399 @samp{!} for the Hitachi SH;
1400 @end ifset
1401 @ifset SPARC
1402 @samp{!} on the SPARC;
1403 @end ifset
1404 @ifset M680X0
1405 @samp{|} on the 680x0;
1406 @end ifset
1407 @ifset VAX
1408 @samp{#} on the Vax;
1409 @end ifset
1410 @ifset Z8000
1411 @samp{!} for the Z8000;
1412 @end ifset
1413 see @ref{Machine Dependencies}.  @refill
1414 @c FIXME What about i386, m88k, i860?
1415
1416 @ifset GENERIC
1417 On some machines there are two different line comment characters.  One
1418 character only begins a comment if it is the first non-whitespace character on
1419 a line, while the other always begins a comment.
1420 @end ifset
1421
1422 @kindex #
1423 @cindex lines starting with @code{#}
1424 @cindex logical line numbers
1425 To be compatible with past assemblers, lines that begin with @samp{#} have a
1426 special interpretation.  Following the @samp{#} should be an absolute
1427 expression (@pxref{Expressions}): the logical line number of the @emph{next}
1428 line.  Then a string (@pxref{Strings,, Strings}) is allowed: if present it is a
1429 new logical file name.  The rest of the line, if any, should be whitespace.
1430
1431 If the first non-whitespace characters on the line are not numeric,
1432 the line is ignored.  (Just like a comment.)
1433
1434 @smallexample
1435                           # This is an ordinary comment.
1436 # 42-6 "new_file_name"    # New logical file name
1437                           # This is logical line # 36.
1438 @end smallexample
1439 This feature is deprecated, and may disappear from future versions
1440 of @code{@value{AS}}.
1441
1442 @node Symbol Intro
1443 @section Symbols
1444
1445 @cindex characters used in symbols
1446 @ifclear SPECIAL-SYMS
1447 A @dfn{symbol} is one or more characters chosen from the set of all
1448 letters (both upper and lower case), digits and the three characters
1449 @samp{_.$}.
1450 @end ifclear
1451 @ifset SPECIAL-SYMS
1452 @ifclear GENERIC
1453 @ifset H8
1454 A @dfn{symbol} is one or more characters chosen from the set of all
1455 letters (both upper and lower case), digits and the three characters
1456 @samp{._$}.  (Save that, on the H8/300 only, you may not use @samp{$} in
1457 symbol names.)
1458 @end ifset
1459 @end ifclear
1460 @end ifset
1461 @ifset GENERIC
1462 On most machines, you can also use @code{$} in symbol names; exceptions
1463 are noted in @ref{Machine Dependencies}.
1464 @end ifset
1465 No symbol may begin with a digit.  Case is significant.
1466 There is no length limit: all characters are significant.  Symbols are
1467 delimited by characters not in that set, or by the beginning of a file
1468 (since the source program must end with a newline, the end of a file is
1469 not a possible symbol delimiter).  @xref{Symbols}.
1470 @cindex length of symbols
1471
1472 @node Statements
1473 @section Statements
1474
1475 @cindex statements, structure of
1476 @cindex line separator character
1477 @cindex statement separator character
1478 @ifclear GENERIC
1479 @ifclear abnormal-separator
1480 A @dfn{statement} ends at a newline character (@samp{\n}) or at a
1481 semicolon (@samp{;}).  The newline or semicolon is considered part of
1482 the preceding statement.  Newlines and semicolons within character
1483 constants are an exception: they do not end statements.
1484 @end ifclear
1485 @ifset abnormal-separator
1486 @ifset A29K
1487 A @dfn{statement} ends at a newline character (@samp{\n}) or an ``at''
1488 sign (@samp{@@}).  The newline or at sign is considered part of the
1489 preceding statement.  Newlines and at signs within character constants
1490 are an exception: they do not end statements.
1491 @end ifset
1492 @ifset HPPA
1493 A @dfn{statement} ends at a newline character (@samp{\n}) or an exclamation 
1494 point (@samp{!}).  The newline or exclamation point is considered part of the
1495 preceding statement.  Newlines and exclamation points within character
1496 constants are an exception: they do not end statements.
1497 @end ifset
1498 @ifset H8
1499 A @dfn{statement} ends at a newline character (@samp{\n}); or (for the
1500 H8/300) a dollar sign (@samp{$}); or (for the
1501 Hitachi-SH or the
1502 H8/500) a semicolon
1503 (@samp{;}).  The newline or separator character is considered part of
1504 the preceding statement.  Newlines and separators within character
1505 constants are an exception: they do not end statements.
1506 @end ifset
1507 @end ifset
1508 @end ifclear
1509 @ifset GENERIC
1510 A @dfn{statement} ends at a newline character (@samp{\n}) or line
1511 separator character.  (The line separator is usually @samp{;}, unless
1512 this conflicts with the comment character; @pxref{Machine Dependencies}.)  The
1513 newline or separator character is considered part of the preceding
1514 statement.  Newlines and separators within character constants are an
1515 exception: they do not end statements.
1516 @end ifset
1517
1518 @cindex newline, required at file end
1519 @cindex EOF, newline must precede
1520 It is an error to end any statement with end-of-file:  the last
1521 character of any input file should be a newline.@refill
1522
1523 @cindex continuing statements
1524 @cindex multi-line statements
1525 @cindex statement on multiple lines
1526 You may write a statement on more than one line if you put a
1527 backslash (@kbd{\}) immediately in front of any newlines within the
1528 statement.  When @code{@value{AS}} reads a backslashed newline both
1529 characters are ignored.  You can even put backslashed newlines in
1530 the middle of symbol names without changing the meaning of your
1531 source program.
1532
1533 An empty statement is allowed, and may include whitespace.  It is ignored.
1534
1535 @cindex instructions and directives
1536 @cindex directives and instructions
1537 @c "key symbol" is not used elsewhere in the document; seems pedantic to
1538 @c @defn{} it in that case, as was done previously...  doc@cygnus.com,
1539 @c 13feb91.
1540 A statement begins with zero or more labels, optionally followed by a
1541 key symbol which determines what kind of statement it is.  The key
1542 symbol determines the syntax of the rest of the statement.  If the
1543 symbol begins with a dot @samp{.} then the statement is an assembler
1544 directive: typically valid for any computer.  If the symbol begins with
1545 a letter the statement is an assembly language @dfn{instruction}: it
1546 assembles into a machine language instruction.
1547 @ifset GENERIC
1548 Different versions of @code{@value{AS}} for different computers
1549 recognize different instructions.  In fact, the same symbol may
1550 represent a different instruction in a different computer's assembly
1551 language.@refill
1552 @end ifset
1553
1554 @cindex @code{:} (label)
1555 @cindex label (@code{:})
1556 A label is a symbol immediately followed by a colon (@code{:}).
1557 Whitespace before a label or after a colon is permitted, but you may not
1558 have whitespace between a label's symbol and its colon. @xref{Labels}.
1559
1560 @ifset HPPA
1561 For HPPA targets, labels need not be immediately followed by a colon, but 
1562 the definition of a label must begin in column zero.  This also implies that
1563 only one label may be defined on each line.
1564 @end ifset
1565
1566 @smallexample
1567 label:     .directive    followed by something
1568 another_label:           # This is an empty statement.
1569            instruction   operand_1, operand_2, @dots{}
1570 @end smallexample
1571
1572 @node Constants
1573 @section Constants
1574
1575 @cindex constants
1576 A constant is a number, written so that its value is known by
1577 inspection, without knowing any context.  Like this:
1578 @smallexample
1579 @group
1580 .byte  74, 0112, 092, 0x4A, 0X4a, 'J, '\J # All the same value.
1581 .ascii "Ring the bell\7"                  # A string constant.
1582 .octa  0x123456789abcdef0123456789ABCDEF0 # A bignum.
1583 .float 0f-314159265358979323846264338327\
1584 95028841971.693993751E-40                 # - pi, a flonum.
1585 @end group
1586 @end smallexample
1587
1588 @menu
1589 * Characters::                  Character Constants
1590 * Numbers::                     Number Constants
1591 @end menu
1592
1593 @node Characters
1594 @subsection Character Constants
1595
1596 @cindex character constants
1597 @cindex constants, character
1598 There are two kinds of character constants.  A @dfn{character} stands
1599 for one character in one byte and its value may be used in
1600 numeric expressions.  String constants (properly called string
1601 @emph{literals}) are potentially many bytes and their values may not be
1602 used in arithmetic expressions.
1603
1604 @menu
1605 * Strings::                     Strings
1606 * Chars::                       Characters
1607 @end menu
1608
1609 @node Strings
1610 @subsubsection Strings
1611
1612 @cindex string constants
1613 @cindex constants, string
1614 A @dfn{string} is written between double-quotes.  It may contain
1615 double-quotes or null characters.  The way to get special characters
1616 into a string is to @dfn{escape} these characters: precede them with
1617 a backslash @samp{\} character.  For example @samp{\\} represents
1618 one backslash:  the first @code{\} is an escape which tells
1619 @code{@value{AS}} to interpret the second character literally as a backslash
1620 (which prevents @code{@value{AS}} from recognizing the second @code{\} as an
1621 escape character).  The complete list of escapes follows.
1622
1623 @cindex escape codes, character
1624 @cindex character escape codes
1625 @table @kbd
1626 @c      @item \a
1627 @c      Mnemonic for ACKnowledge; for ASCII this is octal code 007.
1628 @c
1629 @cindex @code{\b} (backspace character)
1630 @cindex backspace (@code{\b})
1631 @item \b
1632 Mnemonic for backspace; for ASCII this is octal code 010.
1633
1634 @c      @item \e
1635 @c      Mnemonic for EOText; for ASCII this is octal code 004.
1636 @c
1637 @cindex @code{\f} (formfeed character)
1638 @cindex formfeed (@code{\f})
1639 @item \f
1640 Mnemonic for FormFeed; for ASCII this is octal code 014.
1641
1642 @cindex @code{\n} (newline character)
1643 @cindex newline (@code{\n})
1644 @item \n
1645 Mnemonic for newline; for ASCII this is octal code 012.
1646
1647 @c      @item \p
1648 @c      Mnemonic for prefix; for ASCII this is octal code 033, usually known as @code{escape}.
1649 @c
1650 @cindex @code{\r} (carriage return character)
1651 @cindex carriage return (@code{\r})
1652 @item \r
1653 Mnemonic for carriage-Return; for ASCII this is octal code 015.
1654
1655 @c      @item \s
1656 @c      Mnemonic for space; for ASCII this is octal code 040.  Included for compliance with
1657 @c      other assemblers.
1658 @c
1659 @cindex @code{\t} (tab)
1660 @cindex tab (@code{\t})
1661 @item \t
1662 Mnemonic for horizontal Tab; for ASCII this is octal code 011.
1663
1664 @c      @item \v
1665 @c      Mnemonic for Vertical tab; for ASCII this is octal code 013.
1666 @c      @item \x @var{digit} @var{digit} @var{digit}
1667 @c      A hexadecimal character code.  The numeric code is 3 hexadecimal digits.
1668 @c
1669 @cindex @code{\@var{ddd}} (octal character code)
1670 @cindex octal character code (@code{\@var{ddd}})
1671 @item \ @var{digit} @var{digit} @var{digit}
1672 An octal character code.  The numeric code is 3 octal digits.
1673 For compatibility with other Unix systems, 8 and 9 are accepted as digits:
1674 for example, @code{\008} has the value 010, and @code{\009} the value 011.
1675
1676 @cindex @code{\@var{xd...}} (hex character code)
1677 @cindex hex character code (@code{\@var{xd...}})
1678 @item \@code{x} @var{hex-digits...}
1679 A hex character code.  All trailing hex digits are combined.  Either upper or
1680 lower case @code{x} works.
1681
1682 @cindex @code{\\} (@samp{\} character)
1683 @cindex backslash (@code{\\})
1684 @item \\
1685 Represents one @samp{\} character.
1686
1687 @c      @item \'
1688 @c      Represents one @samp{'} (accent acute) character.
1689 @c      This is needed in single character literals
1690 @c      (@xref{Characters,,Character Constants}.) to represent
1691 @c      a @samp{'}.
1692 @c
1693 @cindex @code{\"} (doublequote character)
1694 @cindex doublequote (@code{\"})
1695 @item \"
1696 Represents one @samp{"} character.  Needed in strings to represent
1697 this character, because an unescaped @samp{"} would end the string.
1698
1699 @item \ @var{anything-else}
1700 Any other character when escaped by @kbd{\} gives a warning, but
1701 assembles as if the @samp{\} was not present.  The idea is that if
1702 you used an escape sequence you clearly didn't want the literal
1703 interpretation of the following character.  However @code{@value{AS}} has no
1704 other interpretation, so @code{@value{AS}} knows it is giving you the wrong
1705 code and warns you of the fact.
1706 @end table
1707
1708 Which characters are escapable, and what those escapes represent,
1709 varies widely among assemblers.  The current set is what we think
1710 the BSD 4.2 assembler recognizes, and is a subset of what most C
1711 compilers recognize.  If you are in doubt, do not use an escape
1712 sequence.
1713
1714 @node Chars
1715 @subsubsection Characters
1716
1717 @cindex single character constant
1718 @cindex character, single
1719 @cindex constant, single character
1720 A single character may be written as a single quote immediately
1721 followed by that character.  The same escapes apply to characters as
1722 to strings.  So if you want to write the character backslash, you
1723 must write @kbd{'\\} where the first @code{\} escapes the second
1724 @code{\}.  As you can see, the quote is an acute accent, not a
1725 grave accent.  A newline
1726 @ifclear GENERIC
1727 @ifclear abnormal-separator
1728 (or semicolon @samp{;})
1729 @end ifclear
1730 @ifset abnormal-separator
1731 @ifset A29K
1732 (or at sign @samp{@@})
1733 @end ifset
1734 @ifset H8
1735 (or dollar sign @samp{$}, for the H8/300; or semicolon @samp{;} for the
1736 Hitachi SH or
1737 H8/500)
1738 @end ifset
1739 @end ifset
1740 @end ifclear
1741 immediately following an acute accent is taken as a literal character
1742 and does not count as the end of a statement.  The value of a character
1743 constant in a numeric expression is the machine's byte-wide code for
1744 that character.  @code{@value{AS}} assumes your character code is ASCII:
1745 @kbd{'A} means 65, @kbd{'B} means 66, and so on. @refill
1746
1747 @node Numbers
1748 @subsection Number Constants
1749
1750 @cindex constants, number
1751 @cindex number constants
1752 @code{@value{AS}} distinguishes three kinds of numbers according to how they
1753 are stored in the target machine.  @emph{Integers} are numbers that
1754 would fit into an @code{int} in the C language.  @emph{Bignums} are
1755 integers, but they are stored in more than 32 bits.  @emph{Flonums}
1756 are floating point numbers, described below.
1757
1758 @menu
1759 * Integers::                    Integers
1760 * Bignums::                     Bignums
1761 * Flonums::                     Flonums
1762 @ifclear GENERIC
1763 @ifset I960
1764 * Bit Fields::                  Bit Fields
1765 @end ifset
1766 @end ifclear
1767 @end menu
1768
1769 @node Integers
1770 @subsubsection Integers
1771 @cindex integers
1772 @cindex constants, integer
1773
1774 @cindex binary integers
1775 @cindex integers, binary
1776 A binary integer is @samp{0b} or @samp{0B} followed by zero or more of
1777 the binary digits @samp{01}.
1778
1779 @cindex octal integers
1780 @cindex integers, octal
1781 An octal integer is @samp{0} followed by zero or more of the octal
1782 digits (@samp{01234567}).
1783
1784 @cindex decimal integers
1785 @cindex integers, decimal
1786 A decimal integer starts with a non-zero digit followed by zero or
1787 more digits (@samp{0123456789}).
1788
1789 @cindex hexadecimal integers
1790 @cindex integers, hexadecimal
1791 A hexadecimal integer is @samp{0x} or @samp{0X} followed by one or
1792 more hexadecimal digits chosen from @samp{0123456789abcdefABCDEF}.
1793
1794 Integers have the usual values.  To denote a negative integer, use
1795 the prefix operator @samp{-} discussed under expressions
1796 (@pxref{Prefix Ops,,Prefix Operators}).
1797
1798 @node Bignums
1799 @subsubsection Bignums
1800
1801 @cindex bignums
1802 @cindex constants, bignum
1803 A @dfn{bignum} has the same syntax and semantics as an integer
1804 except that the number (or its negative) takes more than 32 bits to
1805 represent in binary.  The distinction is made because in some places
1806 integers are permitted while bignums are not.
1807
1808 @node Flonums
1809 @subsubsection Flonums
1810 @cindex flonums
1811 @cindex floating point numbers
1812 @cindex constants, floating point
1813
1814 @cindex precision, floating point
1815 A @dfn{flonum} represents a floating point number.  The translation is
1816 indirect: a decimal floating point number from the text is converted by
1817 @code{@value{AS}} to a generic binary floating point number of more than
1818 sufficient precision.  This generic floating point number is converted
1819 to a particular computer's floating point format (or formats) by a
1820 portion of @code{@value{AS}} specialized to that computer.
1821
1822 A flonum is written by writing (in order)
1823 @itemize @bullet
1824 @item
1825 The digit @samp{0}.
1826 @ifset HPPA
1827 (@samp{0} is optional on the HPPA.)
1828 @end ifset
1829
1830 @item
1831 A letter, to tell @code{@value{AS}} the rest of the number is a flonum.
1832 @ifset GENERIC
1833 @kbd{e} is recommended.  Case is not important.
1834 @ignore
1835 @c FIXME: verify if flonum syntax really this vague for most cases
1836 (Any otherwise illegal letter works here, but that might be changed.  Vax BSD
1837 4.2 assembler seems to allow any of @samp{defghDEFGH}.)
1838 @end ignore
1839
1840 On the H8/300, H8/500,
1841 Hitachi SH,
1842 and AMD 29K architectures, the letter must be
1843 one of the letters @samp{DFPRSX} (in upper or lower case).
1844
1845 @c start-sanitize-arc
1846 On the ARC, the letter one of the letters @samp{DFRS}
1847 (in upper or lower case).
1848 @c end-sanitize-arc
1849
1850 On the Intel 960 architecture, the letter must be
1851 one of the letters @samp{DFT} (in upper or lower case).
1852
1853 On the HPPA architecture, the letter must be @samp{E} (upper case only).
1854 @end ifset
1855 @ifclear GENERIC
1856 @ifset A29K
1857 One of the letters @samp{DFPRSX} (in upper or lower case).
1858 @end ifset
1859 @c start-sanitize-arc
1860 @ifset ARC
1861 One of the letters @samp{DFRS} (in upper or lower case).
1862 @end ifset
1863 @c end-sanitize-arc
1864 @ifset H8
1865 One of the letters @samp{DFPRSX} (in upper or lower case).
1866 @end ifset
1867 @ifset HPPA
1868 The letter @samp{E} (upper case only).
1869 @end ifset
1870 @ifset I960
1871 One of the letters @samp{DFT} (in upper or lower case).
1872 @end ifset
1873 @end ifclear
1874
1875 @item
1876 An optional sign: either @samp{+} or @samp{-}.
1877
1878 @item
1879 An optional @dfn{integer part}: zero or more decimal digits.
1880
1881 @item
1882 An optional @dfn{fractional part}: @samp{.} followed by zero
1883 or more decimal digits.
1884
1885 @item
1886 An optional exponent, consisting of:
1887
1888 @itemize @bullet
1889 @item
1890 An @samp{E} or @samp{e}.
1891 @c I can't find a config where "EXP_CHARS" is other than 'eE', but in
1892 @c principle this can perfectly well be different on different targets.
1893 @item
1894 Optional sign: either @samp{+} or @samp{-}.
1895 @item
1896 One or more decimal digits.
1897 @end itemize
1898
1899 @end itemize
1900
1901 At least one of the integer part or the fractional part must be
1902 present.  The floating point number has the usual base-10 value.
1903
1904 @code{@value{AS}} does all processing using integers.  Flonums are computed
1905 independently of any floating point hardware in the computer running
1906 @code{@value{AS}}.
1907
1908 @ifclear GENERIC
1909 @ifset I960
1910 @c Bit fields are written as a general facility but are also controlled
1911 @c by a conditional-compilation flag---which is as of now (21mar91)
1912 @c turned on only by the i960 config of GAS.
1913 @node Bit Fields
1914 @subsubsection Bit Fields
1915
1916 @cindex bit fields
1917 @cindex constants, bit field
1918 You can also define numeric constants as @dfn{bit fields}.
1919 specify two numbers separated by a colon---
1920 @example
1921 @var{mask}:@var{value}
1922 @end example
1923 @noindent
1924 @code{@value{AS}} applies a bitwise @sc{and} between @var{mask} and
1925 @var{value}.
1926
1927 The resulting number is then packed
1928 @ifset GENERIC
1929 @c this conditional paren in case bit fields turned on elsewhere than 960
1930 (in host-dependent byte order)
1931 @end ifset
1932 into a field whose width depends on which assembler directive has the
1933 bit-field as its argument.  Overflow (a result from the bitwise and
1934 requiring more binary digits to represent) is not an error; instead,
1935 more constants are generated, of the specified width, beginning with the
1936 least significant digits.@refill
1937
1938 The directives @code{.byte}, @code{.hword}, @code{.int}, @code{.long},
1939 @code{.short}, and @code{.word} accept bit-field arguments.
1940 @end ifset
1941 @end ifclear
1942
1943 @node Sections
1944 @chapter Sections and Relocation
1945 @cindex sections
1946 @cindex relocation
1947
1948 @menu
1949 * Secs Background::             Background
1950 * Ld Sections::                 @value{LD} Sections
1951 * As Sections::                 @value{AS} Internal Sections
1952 * Sub-Sections::                Sub-Sections
1953 * bss::                         bss Section
1954 @end menu
1955
1956 @node Secs Background
1957 @section Background
1958
1959 Roughly, a section is a range of addresses, with no gaps; all data
1960 ``in'' those addresses is treated the same for some particular purpose.
1961 For example there may be a ``read only'' section.
1962
1963 @cindex linker, and assembler
1964 @cindex assembler, and linker
1965 The linker @code{@value{LD}} reads many object files (partial programs) and
1966 combines their contents to form a runnable program.  When @code{@value{AS}}
1967 emits an object file, the partial program is assumed to start at address 0.
1968 @code{@value{LD}} assigns the final addresses for the partial program, so that
1969 different partial programs do not overlap.  This is actually an
1970 oversimplification, but it suffices to explain how @code{@value{AS}} uses
1971 sections.
1972
1973 @code{@value{LD}} moves blocks of bytes of your program to their run-time
1974 addresses.  These blocks slide to their run-time addresses as rigid
1975 units; their length does not change and neither does the order of bytes
1976 within them.  Such a rigid unit is called a @emph{section}.  Assigning
1977 run-time addresses to sections is called @dfn{relocation}.  It includes
1978 the task of adjusting mentions of object-file addresses so they refer to
1979 the proper run-time addresses.
1980 @ifset H8
1981 For the H8/300 and H8/500,
1982 and for the Hitachi SH,
1983 @code{@value{AS}} pads sections if needed to
1984 ensure they end on a word (sixteen bit) boundary.
1985 @end ifset
1986
1987 @cindex standard @code{@value{AS}} sections
1988 An object file written by @code{@value{AS}} has at least three sections, any
1989 of which may be empty.  These are named @dfn{text}, @dfn{data} and
1990 @dfn{bss} sections.
1991
1992 @ifset COFF
1993 @ifset GENERIC
1994 When it generates COFF output,
1995 @end ifset
1996 @code{@value{AS}} can also generate whatever other named sections you specify
1997 using the @samp{.section} directive (@pxref{Section,,@code{.section}}).
1998 If you do not use any directives that place output in the @samp{.text}
1999 or @samp{.data} sections, these sections still exist, but are empty.
2000 @end ifset
2001
2002 @ifset HPPA
2003 @ifset GENERIC
2004 When @code{@value{AS}} generates SOM or ELF output for the HPPA,
2005 @end ifset
2006 @code{@value{AS}} can also generate whatever other named sections you
2007 specify using the @samp{.space} and @samp{.subspace} directives.  See
2008 @cite{HP9000 Series 800 Assembly Language Reference Manual}
2009 (HP 92432-90001) for details on the @samp{.space} and @samp{.subspace}
2010 assembler directives.
2011
2012 @ifset SOM
2013 Additionally, @code{@value{AS}} uses different names for the standard
2014 text, data, and bss sections when generating SOM output.  Program text
2015 is placed into the @samp{$CODE$} section, data into @samp{$DATA$}, and
2016 BSS into @samp{$BSS$}.
2017 @end ifset
2018 @end ifset
2019
2020 Within the object file, the text section starts at address @code{0}, the
2021 data section follows, and the bss section follows the data section.
2022
2023 @ifset HPPA
2024 When generating either SOM or ELF output files on the HPPA, the text
2025 section starts at address @code{0}, the data section at address
2026 @code{0x4000000}, and the bss section follows the data section.
2027 @end ifset
2028
2029 To let @code{@value{LD}} know which data changes when the sections are
2030 relocated, and how to change that data, @code{@value{AS}} also writes to the
2031 object file details of the relocation needed.  To perform relocation
2032 @code{@value{LD}} must know, each time an address in the object
2033 file is mentioned:
2034 @itemize @bullet
2035 @item
2036 Where in the object file is the beginning of this reference to
2037 an address?
2038 @item
2039 How long (in bytes) is this reference?
2040 @item
2041 Which section does the address refer to?  What is the numeric value of
2042 @display
2043 (@var{address}) @minus{} (@var{start-address of section})?
2044 @end display
2045 @item
2046 Is the reference to an address ``Program-Counter relative''?
2047 @end itemize
2048
2049 @cindex addresses, format of
2050 @cindex section-relative addressing
2051 In fact, every address @code{@value{AS}} ever uses is expressed as
2052 @display
2053 (@var{section}) + (@var{offset into section})
2054 @end display
2055 @noindent
2056 Further, most expressions @code{@value{AS}} computes have this section-relative
2057 nature.
2058 @ifset SOM
2059 (For some object formats, such as SOM for the HPPA, some expressions are
2060 symbol-relative instead.)
2061 @end ifset
2062
2063 In this manual we use the notation @{@var{secname} @var{N}@} to mean ``offset
2064 @var{N} into section @var{secname}.''
2065
2066 Apart from text, data and bss sections you need to know about the
2067 @dfn{absolute} section.  When @code{@value{LD}} mixes partial programs,
2068 addresses in the absolute section remain unchanged.  For example, address
2069 @code{@{absolute 0@}} is ``relocated'' to run-time address 0 by
2070 @code{@value{LD}}.  Although the linker never arranges two partial programs'
2071 data sections with overlapping addresses after linking, @emph{by definition}
2072 their absolute sections must overlap.  Address @code{@{absolute@ 239@}} in one
2073 part of a program is always the same address when the program is running as
2074 address @code{@{absolute@ 239@}} in any other part of the program.
2075
2076 The idea of sections is extended to the @dfn{undefined} section.  Any
2077 address whose section is unknown at assembly time is by definition
2078 rendered @{undefined @var{U}@}---where @var{U} is filled in later.
2079 Since numbers are always defined, the only way to generate an undefined
2080 address is to mention an undefined symbol.  A reference to a named
2081 common block would be such a symbol: its value is unknown at assembly
2082 time so it has section @emph{undefined}.
2083
2084 By analogy the word @emph{section} is used to describe groups of sections in
2085 the linked program.  @code{@value{LD}} puts all partial programs' text
2086 sections in contiguous addresses in the linked program.  It is
2087 customary to refer to the @emph{text section} of a program, meaning all
2088 the addresses of all partial programs' text sections.  Likewise for
2089 data and bss sections.
2090
2091 Some sections are manipulated by @code{@value{LD}}; others are invented for
2092 use of @code{@value{AS}} and have no meaning except during assembly.
2093
2094 @node Ld Sections
2095 @section @value{LD} Sections
2096 @code{@value{LD}} deals with just four kinds of sections, summarized below.
2097
2098 @table @strong
2099
2100 @ifset COFF
2101 @cindex named sections
2102 @cindex sections, named
2103 @item named sections
2104 @end ifset
2105 @ifset aout-bout
2106 @cindex text section
2107 @cindex data section
2108 @itemx text section
2109 @itemx data section
2110 @end ifset
2111 These sections hold your program.  @code{@value{AS}} and @code{@value{LD}} treat them as
2112 separate but equal sections.  Anything you can say of one section is
2113 true another.
2114 @ifset aout-bout
2115 When the program is running, however, it is
2116 customary for the text section to be unalterable.  The
2117 text section is often shared among processes: it contains
2118 instructions, constants and the like.  The data section of a running
2119 program is usually alterable: for example, C variables would be stored
2120 in the data section.
2121 @end ifset
2122
2123 @cindex bss section
2124 @item bss section
2125 This section contains zeroed bytes when your program begins running.  It
2126 is used to hold unitialized variables or common storage.  The length of
2127 each partial program's bss section is important, but because it starts
2128 out containing zeroed bytes there is no need to store explicit zero
2129 bytes in the object file.  The bss section was invented to eliminate
2130 those explicit zeros from object files.
2131
2132 @cindex absolute section
2133 @item absolute section
2134 Address 0 of this section is always ``relocated'' to runtime address 0.
2135 This is useful if you want to refer to an address that @code{@value{LD}} must
2136 not change when relocating.  In this sense we speak of absolute
2137 addresses being ``unrelocatable'': they do not change during relocation.
2138
2139 @cindex undefined section
2140 @item undefined section
2141 This ``section'' is a catch-all for address references to objects not in
2142 the preceding sections.
2143 @c FIXME: ref to some other doc on obj-file formats could go here.
2144 @end table
2145
2146 @cindex relocation example
2147 An idealized example of three relocatable sections follows.
2148 @ifset COFF
2149 The example uses the traditional section names @samp{.text} and @samp{.data}.
2150 @end ifset
2151 Memory addresses are on the horizontal axis.
2152
2153 @c TEXI2ROFF-KILL
2154 @ifinfo
2155 @c END TEXI2ROFF-KILL
2156 @smallexample
2157                       +-----+----+--+
2158 partial program # 1:  |ttttt|dddd|00|
2159                       +-----+----+--+
2160
2161                       text   data bss
2162                       seg.   seg. seg.
2163
2164                       +---+---+---+
2165 partial program # 2:  |TTT|DDD|000|
2166                       +---+---+---+
2167
2168                       +--+---+-----+--+----+---+-----+~~
2169 linked program:       |  |TTT|ttttt|  |dddd|DDD|00000|
2170                       +--+---+-----+--+----+---+-----+~~
2171
2172     addresses:        0 @dots{}
2173 @end smallexample
2174 @c TEXI2ROFF-KILL
2175 @end ifinfo
2176 @need 5000
2177 @tex
2178
2179 \line{\it Partial program \#1: \hfil}
2180 \line{\ibox{2.5cm}{\tt text}\ibox{2cm}{\tt data}\ibox{1cm}{\tt bss}\hfil}
2181 \line{\boxit{2.5cm}{\tt ttttt}\boxit{2cm}{\tt dddd}\boxit{1cm}{\tt 00}\hfil}
2182
2183 \line{\it Partial program \#2: \hfil}
2184 \line{\ibox{1cm}{\tt text}\ibox{1.5cm}{\tt data}\ibox{1cm}{\tt bss}\hfil}
2185 \line{\boxit{1cm}{\tt TTT}\boxit{1.5cm}{\tt DDDD}\boxit{1cm}{\tt 000}\hfil}
2186
2187 \line{\it linked program: \hfil}
2188 \line{\ibox{.5cm}{}\ibox{1cm}{\tt text}\ibox{2.5cm}{}\ibox{.75cm}{}\ibox{2cm}{\tt data}\ibox{1.5cm}{}\ibox{2cm}{\tt bss}\hfil}
2189 \line{\boxit{.5cm}{}\boxit{1cm}{\tt TTT}\boxit{2.5cm}{\tt
2190 ttttt}\boxit{.75cm}{}\boxit{2cm}{\tt dddd}\boxit{1.5cm}{\tt
2191 DDDD}\boxit{2cm}{\tt 00000}\ \dots\hfil}
2192
2193 \line{\it addresses: \hfil}
2194 \line{0\dots\hfil}
2195
2196 @end tex
2197 @c END TEXI2ROFF-KILL
2198
2199 @node As Sections
2200 @section @value{AS} Internal Sections
2201
2202 @cindex internal @code{@value{AS}} sections
2203 @cindex sections in messages, internal
2204 These sections are meant only for the internal use of @code{@value{AS}}.  They
2205 have no meaning at run-time.  You do not really need to know about these
2206 sections for most purposes; but they can be mentioned in @code{@value{AS}}
2207 warning messages, so it might be helpful to have an idea of their
2208 meanings to @code{@value{AS}}.  These sections are used to permit the
2209 value of every expression in your assembly language program to be a
2210 section-relative address.
2211
2212 @table @b
2213 @cindex assembler internal logic error
2214 @item ASSEMBLER-INTERNAL-LOGIC-ERROR!
2215 An internal assembler logic error has been found.  This means there is a
2216 bug in the assembler.
2217
2218 @cindex expr (internal section)
2219 @item expr section
2220 The assembler stores complex expression internally as combinations of
2221 symbols.  When it needs to represent an expression as a symbol, it puts
2222 it in the expr section.
2223 @c FIXME item debug
2224 @c FIXME item transfer[t] vector preload
2225 @c FIXME item transfer[t] vector postload
2226 @c FIXME item register
2227 @end table
2228
2229 @node Sub-Sections
2230 @section Sub-Sections
2231
2232 @cindex numbered subsections
2233 @cindex grouping data
2234 @ifset aout-bout
2235 Assembled bytes
2236 @ifset COFF
2237 conventionally
2238 @end ifset
2239 fall into two sections: text and data.
2240 @end ifset
2241 You may have separate groups of
2242 @ifset GENERIC
2243 data in named sections
2244 @end ifset
2245 @ifclear GENERIC
2246 @ifclear aout-bout
2247 data in named sections
2248 @end ifclear
2249 @ifset aout-bout
2250 text or data
2251 @end ifset
2252 @end ifclear
2253 that you want to end up near to each other in the object file, even though they
2254 are not contiguous in the assembler source.  @code{@value{AS}} allows you to
2255 use @dfn{subsections} for this purpose.  Within each section, there can be
2256 numbered subsections with values from 0 to 8192.  Objects assembled into the
2257 same subsection go into the object file together with other objects in the same
2258 subsection.  For example, a compiler might want to store constants in the text
2259 section, but might not want to have them interspersed with the program being
2260 assembled.  In this case, the compiler could issue a @samp{.text 0} before each
2261 section of code being output, and a @samp{.text 1} before each group of
2262 constants being output.
2263
2264 Subsections are optional.  If you do not use subsections, everything
2265 goes in subsection number zero.
2266
2267 @ifset GENERIC
2268 Each subsection is zero-padded up to a multiple of four bytes.
2269 (Subsections may be padded a different amount on different flavors
2270 of @code{@value{AS}}.)
2271 @end ifset
2272 @ifclear GENERIC
2273 @ifset H8
2274 On the H8/300 and H8/500 platforms, each subsection is zero-padded to a word
2275 boundary (two bytes).
2276 The same is true on the Hitachi SH.
2277 @end ifset
2278 @ifset I960
2279 @c FIXME section padding (alignment)?
2280 @c Rich Pixley says padding here depends on target obj code format; that
2281 @c doesn't seem particularly useful to say without further elaboration,
2282 @c so for now I say nothing about it.  If this is a generic BFD issue,
2283 @c these paragraphs might need to vanish from this manual, and be
2284 @c discussed in BFD chapter of binutils (or some such).
2285 @end ifset
2286 @ifset A29K
2287 On the AMD 29K family, no particular padding is added to section or
2288 subsection sizes; @value{AS} forces no alignment on this platform.
2289 @end ifset
2290 @end ifclear
2291
2292 Subsections appear in your object file in numeric order, lowest numbered
2293 to highest.  (All this to be compatible with other people's assemblers.)
2294 The object file contains no representation of subsections; @code{@value{LD}} and
2295 other programs that manipulate object files see no trace of them.
2296 They just see all your text subsections as a text section, and all your
2297 data subsections as a data section.
2298
2299 To specify which subsection you want subsequent statements assembled
2300 into, use a numeric argument to specify it, in a @samp{.text
2301 @var{expression}} or a @samp{.data @var{expression}} statement.
2302 @ifset COFF
2303 @ifset GENERIC
2304 When generating COFF output, you
2305 @end ifset
2306 @ifclear GENERIC
2307 You
2308 @end ifclear
2309 can also use an extra subsection
2310 argument with arbitrary named sections: @samp{.section @var{name},
2311 @var{expression}}.
2312 @end ifset
2313 @var{Expression} should be an absolute expression.
2314 (@xref{Expressions}.)  If you just say @samp{.text} then @samp{.text 0}
2315 is assumed.  Likewise @samp{.data} means @samp{.data 0}.  Assembly
2316 begins in @code{text 0}.  For instance:
2317 @smallexample
2318 .text 0     # The default subsection is text 0 anyway.
2319 .ascii "This lives in the first text subsection. *"
2320 .text 1
2321 .ascii "But this lives in the second text subsection."
2322 .data 0
2323 .ascii "This lives in the data section,"
2324 .ascii "in the first data subsection."
2325 .text 0
2326 .ascii "This lives in the first text section,"
2327 .ascii "immediately following the asterisk (*)."
2328 @end smallexample
2329
2330 Each section has a @dfn{location counter} incremented by one for every byte
2331 assembled into that section.  Because subsections are merely a convenience
2332 restricted to @code{@value{AS}} there is no concept of a subsection location
2333 counter.  There is no way to directly manipulate a location counter---but the
2334 @code{.align} directive changes it, and any label definition captures its
2335 current value.  The location counter of the section where statements are being
2336 assembled is said to be the @dfn{active} location counter.
2337
2338 @node bss
2339 @section bss Section
2340
2341 @cindex bss section
2342 @cindex common variable storage
2343 The bss section is used for local common variable storage.
2344 You may allocate address space in the bss section, but you may
2345 not dictate data to load into it before your program executes.  When
2346 your program starts running, all the contents of the bss
2347 section are zeroed bytes.
2348
2349 The @code{.lcomm} pseudo-op defines a symbol in the bss section; see
2350 @ref{Lcomm,,@code{.lcomm}}.
2351
2352 The @code{.comm} pseudo-op may be used to declare a common symbol, which is
2353 another form of uninitialized symbol; see @xref{Comm,,@code{.comm}}.
2354
2355 @ifset GENERIC
2356 When assembling for a target which supports multiple sections, such as ELF or
2357 COFF, you may switch into the @code{.bss} section and define symbols as usual;
2358 see @ref{Section,,@code{.section}}.  You may only assemble zero values into the
2359 section.  Typically the section will only contain symbol definitions and
2360 @code{.skip} directives (@pxref{Skip,,@code{.skip}}).
2361 @end ifset
2362
2363 @node Symbols
2364 @chapter Symbols
2365
2366 @cindex symbols
2367 Symbols are a central concept: the programmer uses symbols to name
2368 things, the linker uses symbols to link, and the debugger uses symbols
2369 to debug.
2370
2371 @quotation
2372 @cindex debuggers, and symbol order
2373 @emph{Warning:} @code{@value{AS}} does not place symbols in the object file in
2374 the same order they were declared.  This may break some debuggers.
2375 @end quotation
2376
2377 @menu
2378 * Labels::                      Labels
2379 * Setting Symbols::             Giving Symbols Other Values
2380 * Symbol Names::                Symbol Names
2381 * Dot::                         The Special Dot Symbol
2382 * Symbol Attributes::           Symbol Attributes
2383 @end menu
2384
2385 @node Labels
2386 @section Labels
2387
2388 @cindex labels
2389 A @dfn{label} is written as a symbol immediately followed by a colon
2390 @samp{:}.  The symbol then represents the current value of the
2391 active location counter, and is, for example, a suitable instruction
2392 operand.  You are warned if you use the same symbol to represent two
2393 different locations: the first definition overrides any other
2394 definitions.
2395
2396 @ifset HPPA
2397 On the HPPA, the usual form for a label need not be immediately followed by a
2398 colon, but instead must start in column zero.  Only one label may be defined on
2399 a single line.  To work around this, the HPPA version of @code{@value{AS}} also
2400 provides a special directive @code{.label} for defining labels more flexibly.
2401 @end ifset
2402
2403 @node Setting Symbols
2404 @section Giving Symbols Other Values
2405
2406 @cindex assigning values to symbols
2407 @cindex symbol values, assigning
2408 A symbol can be given an arbitrary value by writing a symbol, followed
2409 by an equals sign @samp{=}, followed by an expression
2410 (@pxref{Expressions}).  This is equivalent to using the @code{.set}
2411 directive.  @xref{Set,,@code{.set}}.
2412
2413 @node Symbol Names
2414 @section Symbol Names
2415
2416 @cindex symbol names
2417 @cindex names, symbol
2418 @ifclear SPECIAL-SYMS
2419 Symbol names begin with a letter or with one of @samp{._}.  On most
2420 machines, you can also use @code{$} in symbol names; exceptions are
2421 noted in @ref{Machine Dependencies}.  That character may be followed by any
2422 string of digits, letters, dollar signs (unless otherwise noted in
2423 @ref{Machine Dependencies}), and underscores.
2424 @end ifclear
2425 @ifset A29K
2426 For the AMD 29K family, @samp{?} is also allowed in the
2427 body of a symbol name, though not at its beginning.
2428 @end ifset
2429
2430 @ifset SPECIAL-SYMS
2431 @ifset H8
2432 Symbol names begin with a letter or with one of @samp{._}.  On the
2433 Hitachi SH or the
2434 H8/500, you can also use @code{$} in symbol names.  That character may
2435 be followed by any string of digits, letters, dollar signs (save on the
2436 H8/300), and underscores.
2437 @end ifset
2438 @end ifset
2439
2440 Case of letters is significant: @code{foo} is a different symbol name
2441 than @code{Foo}.
2442
2443 Each symbol has exactly one name.  Each name in an assembly language program
2444 refers to exactly one symbol.  You may use that symbol name any number of times
2445 in a program.
2446
2447 @subheading Local Symbol Names
2448
2449 @cindex local symbol names
2450 @cindex symbol names, local
2451 @cindex temporary symbol names
2452 @cindex symbol names, temporary
2453 Local symbols help compilers and programmers use names temporarily.
2454 There are ten local symbol names, which are re-used throughout the
2455 program.  You may refer to them using the names @samp{0} @samp{1}
2456 @dots{} @samp{9}.  To define a local symbol, write a label of the form
2457 @samp{@b{N}:} (where @b{N} represents any digit).  To refer to the most
2458 recent previous definition of that symbol write @samp{@b{N}b}, using the
2459 same digit as when you defined the label.  To refer to the next
2460 definition of a local label, write @samp{@b{N}f}---where @b{N} gives you
2461 a choice of 10 forward references.  The @samp{b} stands for
2462 ``backwards'' and the @samp{f} stands for ``forwards''.
2463
2464 Local symbols are not emitted by the current @sc{gnu} C compiler.
2465
2466 There is no restriction on how you can use these labels, but
2467 remember that at any point in the assembly you can refer to at most
2468 10 prior local labels and to at most 10 forward local labels.
2469
2470 Local symbol names are only a notation device.  They are immediately
2471 transformed into more conventional symbol names before the assembler
2472 uses them.  The symbol names stored in the symbol table, appearing in
2473 error messages and optionally emitted to the object file have these
2474 parts:
2475
2476 @table @code
2477 @item L
2478 All local labels begin with @samp{L}. Normally both @code{@value{AS}} and
2479 @code{@value{LD}} forget symbols that start with @samp{L}. These labels are
2480 used for symbols you are never intended to see.  If you use the
2481 @samp{-L} option then @code{@value{AS}} retains these symbols in the
2482 object file. If you also instruct @code{@value{LD}} to retain these symbols,
2483 you may use them in debugging.
2484
2485 @item @var{digit}
2486 If the label is written @samp{0:} then the digit is @samp{0}.
2487 If the label is written @samp{1:} then the digit is @samp{1}.
2488 And so on up through @samp{9:}.
2489
2490 @item @kbd{C-A}
2491 This unusual character is included so you do not accidentally invent
2492 a symbol of the same name.  The character has ASCII value
2493 @samp{\001}.
2494
2495 @item @emph{ordinal number}
2496 This is a serial number to keep the labels distinct.  The first
2497 @samp{0:} gets the number @samp{1}; The 15th @samp{0:} gets the
2498 number @samp{15}; @emph{etc.}.  Likewise for the other labels @samp{1:}
2499 through @samp{9:}.
2500 @end table
2501
2502 For instance, the first @code{1:} is named @code{L1@kbd{C-A}1}, the 44th
2503 @code{3:} is named @code{L3@kbd{C-A}44}.
2504
2505 @node Dot
2506 @section The Special Dot Symbol
2507
2508 @cindex dot (symbol)
2509 @cindex @code{.} (symbol)
2510 @cindex current address
2511 @cindex location counter
2512 The special symbol @samp{.} refers to the current address that
2513 @code{@value{AS}} is assembling into.  Thus, the expression @samp{melvin:
2514 .long .} defines @code{melvin} to contain its own address.
2515 Assigning a value to @code{.} is treated the same as a @code{.org}
2516 directive.  Thus, the expression @samp{.=.+4} is the same as saying
2517 @ifclear no-space-dir
2518 @samp{.space 4}.
2519 @end ifclear
2520 @ifset no-space-dir
2521 @ifset A29K
2522 @samp{.block 4}.
2523 @end ifset
2524 @end ifset
2525
2526 @node Symbol Attributes
2527 @section Symbol Attributes
2528
2529 @cindex symbol attributes
2530 @cindex attributes, symbol
2531 Every symbol has, as well as its name, the attributes ``Value'' and
2532 ``Type''.  Depending on output format, symbols can also have auxiliary
2533 attributes.
2534 @ifset INTERNALS
2535 The detailed definitions are in @file{a.out.h}.
2536 @end ifset
2537
2538 If you use a symbol without defining it, @code{@value{AS}} assumes zero for
2539 all these attributes, and probably won't warn you.  This makes the
2540 symbol an externally defined symbol, which is generally what you
2541 would want.
2542
2543 @menu
2544 * Symbol Value::                Value
2545 * Symbol Type::                 Type
2546 @ifset aout-bout
2547 @ifset GENERIC
2548 * a.out Symbols::               Symbol Attributes: @code{a.out}
2549 @end ifset
2550 @ifclear GENERIC
2551 @ifclear BOUT
2552 * a.out Symbols::               Symbol Attributes: @code{a.out}
2553 @end ifclear
2554 @ifset BOUT
2555 * a.out Symbols::               Symbol Attributes: @code{a.out}, @code{b.out}
2556 @end ifset
2557 @end ifclear
2558 @end ifset
2559 @ifset COFF
2560 * COFF Symbols::                Symbol Attributes for COFF
2561 @end ifset
2562 @ifset SOM
2563 * SOM Symbols::                Symbol Attributes for SOM
2564 @end ifset
2565 @end menu
2566
2567 @node Symbol Value
2568 @subsection Value
2569
2570 @cindex value of a symbol
2571 @cindex symbol value
2572 The value of a symbol is (usually) 32 bits.  For a symbol which labels a
2573 location in the text, data, bss or absolute sections the value is the
2574 number of addresses from the start of that section to the label.
2575 Naturally for text, data and bss sections the value of a symbol changes
2576 as @code{@value{LD}} changes section base addresses during linking.  Absolute
2577 symbols' values do not change during linking: that is why they are
2578 called absolute.
2579
2580 The value of an undefined symbol is treated in a special way.  If it is
2581 0 then the symbol is not defined in this assembler source file, and
2582 @code{@value{LD}} tries to determine its value from other files linked into the
2583 same program.  You make this kind of symbol simply by mentioning a symbol
2584 name without defining it.  A non-zero value represents a @code{.comm}
2585 common declaration.  The value is how much common storage to reserve, in
2586 bytes (addresses).  The symbol refers to the first address of the
2587 allocated storage.
2588
2589 @node Symbol Type
2590 @subsection Type
2591
2592 @cindex type of a symbol
2593 @cindex symbol type
2594 The type attribute of a symbol contains relocation (section)
2595 information, any flag settings indicating that a symbol is external, and
2596 (optionally), other information for linkers and debuggers.  The exact
2597 format depends on the object-code output format in use.
2598
2599 @ifset aout-bout
2600 @ifclear GENERIC
2601 @ifset BOUT
2602 @c The following avoids a "widow" subsection title.  @group would be
2603 @c better if it were available outside examples.
2604 @need 1000
2605 @node a.out Symbols
2606 @subsection Symbol Attributes: @code{a.out}, @code{b.out}
2607
2608 @cindex @code{b.out} symbol attributes
2609 @cindex symbol attributes, @code{b.out}
2610 These symbol attributes appear only when @code{@value{AS}} is configured for
2611 one of the Berkeley-descended object output formats---@code{a.out} or
2612 @code{b.out}.
2613
2614 @end ifset
2615 @ifclear BOUT
2616 @node a.out Symbols
2617 @subsection Symbol Attributes: @code{a.out}
2618
2619 @cindex @code{a.out} symbol attributes
2620 @cindex symbol attributes, @code{a.out}
2621
2622 @end ifclear
2623 @end ifclear
2624 @ifset GENERIC
2625 @node a.out Symbols
2626 @subsection Symbol Attributes: @code{a.out}
2627
2628 @cindex @code{a.out} symbol attributes
2629 @cindex symbol attributes, @code{a.out}
2630
2631 @end ifset
2632 @menu
2633 * Symbol Desc::                 Descriptor
2634 * Symbol Other::                Other
2635 @end menu
2636
2637 @node Symbol Desc
2638 @subsubsection Descriptor
2639
2640 @cindex descriptor, of @code{a.out} symbol
2641 This is an arbitrary 16-bit value.  You may establish a symbol's
2642 descriptor value by using a @code{.desc} statement
2643 (@pxref{Desc,,@code{.desc}}).  A descriptor value means nothing to
2644 @code{@value{AS}}.
2645
2646 @node Symbol Other
2647 @subsubsection Other
2648
2649 @cindex other attribute, of @code{a.out} symbol
2650 This is an arbitrary 8-bit value.  It means nothing to @code{@value{AS}}.
2651 @end ifset
2652
2653 @ifset COFF
2654 @node COFF Symbols
2655 @subsection Symbol Attributes for COFF
2656
2657 @cindex COFF symbol attributes
2658 @cindex symbol attributes, COFF
2659
2660 The COFF format supports a multitude of auxiliary symbol attributes;
2661 like the primary symbol attributes, they are set between @code{.def} and
2662 @code{.endef} directives.
2663
2664 @subsubsection Primary Attributes
2665
2666 @cindex primary attributes, COFF symbols
2667 The symbol name is set with @code{.def}; the value and type,
2668 respectively, with @code{.val} and @code{.type}.
2669
2670 @subsubsection Auxiliary Attributes
2671
2672 @cindex auxiliary attributes, COFF symbols
2673 The @code{@value{AS}} directives @code{.dim}, @code{.line}, @code{.scl},
2674 @code{.size}, and @code{.tag} can generate auxiliary symbol table
2675 information for COFF.
2676 @end ifset
2677
2678 @ifset SOM
2679 @node SOM Symbols
2680 @subsection Symbol Attributes for SOM
2681
2682 @cindex SOM symbol attributes
2683 @cindex symbol attributes, SOM
2684
2685 The SOM format for the HPPA supports a multitude of symbol attributes set with
2686 the @code{.EXPORT} and @code{.IMPORT} directives.
2687
2688 The attributes are described in @cite{HP9000 Series 800 Assembly 
2689 Language Reference Manual} (HP 92432-90001) under the @code{IMPORT} and
2690 @code{EXPORT} assembler directive documentation.
2691 @end ifset
2692
2693 @node Expressions
2694 @chapter Expressions
2695
2696 @cindex expressions
2697 @cindex addresses
2698 @cindex numeric values
2699 An @dfn{expression} specifies an address or numeric value.
2700 Whitespace may precede and/or follow an expression.
2701
2702 The result of an expression must be an absolute number, or else an offset into
2703 a particular section.  If an expression is not absolute, and there is not
2704 enough information when @code{@value{AS}} sees the expression to know its
2705 section, a second pass over the source program might be necessary to interpret
2706 the expression---but the second pass is currently not implemented.
2707 @code{@value{AS}} aborts with an error message in this situation.
2708
2709 @menu
2710 * Empty Exprs::                 Empty Expressions
2711 * Integer Exprs::               Integer Expressions
2712 @end menu
2713
2714 @node Empty Exprs
2715 @section Empty Expressions
2716
2717 @cindex empty expressions
2718 @cindex expressions, empty
2719 An empty expression has no value: it is just whitespace or null.
2720 Wherever an absolute expression is required, you may omit the
2721 expression, and @code{@value{AS}} assumes a value of (absolute) 0.  This
2722 is compatible with other assemblers.
2723
2724 @node Integer Exprs
2725 @section Integer Expressions
2726
2727 @cindex integer expressions
2728 @cindex expressions, integer
2729 An @dfn{integer expression} is one or more @emph{arguments} delimited
2730 by @emph{operators}.
2731
2732 @menu
2733 * Arguments::                   Arguments
2734 * Operators::                   Operators
2735 * Prefix Ops::                  Prefix Operators
2736 * Infix Ops::                   Infix Operators
2737 @end menu
2738
2739 @node Arguments
2740 @subsection Arguments
2741
2742 @cindex expression arguments
2743 @cindex arguments in expressions
2744 @cindex operands in expressions
2745 @cindex arithmetic operands
2746 @dfn{Arguments} are symbols, numbers or subexpressions.  In other
2747 contexts arguments are sometimes called ``arithmetic operands''.  In
2748 this manual, to avoid confusing them with the ``instruction operands'' of
2749 the machine language, we use the term ``argument'' to refer to parts of
2750 expressions only, reserving the word ``operand'' to refer only to machine
2751 instruction operands.
2752
2753 Symbols are evaluated to yield @{@var{section} @var{NNN}@} where
2754 @var{section} is one of text, data, bss, absolute,
2755 or undefined.  @var{NNN} is a signed, 2's complement 32 bit
2756 integer.
2757
2758 Numbers are usually integers.
2759
2760 A number can be a flonum or bignum.  In this case, you are warned
2761 that only the low order 32 bits are used, and @code{@value{AS}} pretends
2762 these 32 bits are an integer.  You may write integer-manipulating
2763 instructions that act on exotic constants, compatible with other
2764 assemblers.
2765
2766 @cindex subexpressions
2767 Subexpressions are a left parenthesis @samp{(} followed by an integer
2768 expression, followed by a right parenthesis @samp{)}; or a prefix
2769 operator followed by an argument.
2770
2771 @node Operators
2772 @subsection Operators
2773
2774 @cindex operators, in expressions
2775 @cindex arithmetic functions
2776 @cindex functions, in expressions
2777 @dfn{Operators} are arithmetic functions, like @code{+} or @code{%}.  Prefix
2778 operators are followed by an argument.  Infix operators appear
2779 between their arguments.  Operators may be preceded and/or followed by
2780 whitespace.
2781
2782 @node Prefix Ops
2783 @subsection Prefix Operator
2784
2785 @cindex prefix operators
2786 @code{@value{AS}} has the following @dfn{prefix operators}.  They each take
2787 one argument, which must be absolute.
2788
2789 @c the tex/end tex stuff surrounding this small table is meant to make
2790 @c it align, on the printed page, with the similar table in the next
2791 @c section (which is inside an enumerate).
2792 @tex
2793 \global\advance\leftskip by \itemindent
2794 @end tex
2795
2796 @table @code
2797 @item -
2798 @dfn{Negation}.  Two's complement negation.
2799 @item ~
2800 @dfn{Complementation}.  Bitwise not.
2801 @end table
2802
2803 @tex
2804 \global\advance\leftskip by -\itemindent
2805 @end tex
2806
2807 @node Infix Ops
2808 @subsection Infix Operators
2809
2810 @cindex infix operators
2811 @cindex operators, permitted arguments
2812 @dfn{Infix operators} take two arguments, one on either side.  Operators
2813 have precedence, but operations with equal precedence are performed left
2814 to right.  Apart from @code{+} or @code{-}, both arguments must be
2815 absolute, and the result is absolute.
2816
2817 @enumerate
2818 @cindex operator precedence
2819 @cindex precedence of operators
2820
2821 @item
2822 Highest Precedence
2823
2824 @table @code
2825 @item *
2826 @dfn{Multiplication}.
2827
2828 @item /
2829 @dfn{Division}.  Truncation is the same as the C operator @samp{/}
2830
2831 @item %
2832 @dfn{Remainder}.
2833
2834 @item <
2835 @itemx <<
2836 @dfn{Shift Left}.  Same as the C operator @samp{<<}.
2837
2838 @item >
2839 @itemx >>
2840 @dfn{Shift Right}.  Same as the C operator @samp{>>}.
2841 @end table
2842
2843 @item
2844 Intermediate precedence
2845
2846 @table @code
2847 @item |
2848
2849 @dfn{Bitwise Inclusive Or}.
2850
2851 @item &
2852 @dfn{Bitwise And}.
2853
2854 @item ^
2855 @dfn{Bitwise Exclusive Or}.
2856
2857 @item !
2858 @dfn{Bitwise Or Not}.
2859 @end table
2860
2861 @item
2862 Lowest Precedence
2863
2864 @table @code
2865 @cindex addition, permitted arguments
2866 @cindex plus, permitted arguments
2867 @cindex arguments for addition
2868 @item +
2869 @dfn{Addition}.  If either argument is absolute, the result has the section of
2870 the other argument.  You may not add together arguments from different
2871 sections.
2872
2873 @cindex subtraction, permitted arguments
2874 @cindex minus, permitted arguments
2875 @cindex arguments for subtraction
2876 @item -
2877 @dfn{Subtraction}.  If the right argument is absolute, the
2878 result has the section of the left argument.
2879 If both arguments are in the same section, the result is absolute.
2880 You may not subtract arguments from different sections.
2881 @c FIXME is there still something useful to say about undefined - undefined ?
2882 @end table
2883 @end enumerate
2884
2885 In short, it's only meaningful to add or subtract the @emph{offsets} in an
2886 address; you can only have a defined section in one of the two arguments.
2887
2888 @node Pseudo Ops
2889 @chapter Assembler Directives
2890
2891 @cindex directives, machine independent
2892 @cindex pseudo-ops, machine independent
2893 @cindex machine independent directives
2894 All assembler directives have names that begin with a period (@samp{.}).
2895 The rest of the name is letters, usually in lower case.
2896
2897 This chapter discusses directives that are available regardless of the
2898 target machine configuration for the @sc{gnu} assembler.
2899 @ifset GENERIC
2900 Some machine configurations provide additional directives.
2901 @xref{Machine Dependencies}.
2902 @end ifset
2903 @ifclear GENERIC
2904 @ifset machine-directives
2905 @xref{Machine Dependencies} for additional directives.
2906 @end ifset
2907 @end ifclear
2908
2909 @menu
2910 * Abort::                       @code{.abort}
2911 @ifset COFF
2912 * ABORT::                       @code{.ABORT}
2913 @end ifset
2914
2915 * Align::                       @code{.align @var{abs-expr} , @var{abs-expr}}
2916 * App-File::                    @code{.app-file @var{string}}
2917 * Ascii::                       @code{.ascii "@var{string}"}@dots{}
2918 * Asciz::                       @code{.asciz "@var{string}"}@dots{}
2919 * Balign::                      @code{.balign @var{abs-expr} , @var{abs-expr}}
2920 * Byte::                        @code{.byte @var{expressions}}
2921 * Comm::                        @code{.comm @var{symbol} , @var{length} }
2922 * Data::                        @code{.data @var{subsection}}
2923 @ifset COFF
2924 * Def::                         @code{.def @var{name}}
2925 @end ifset
2926 @ifset aout-bout
2927 * Desc::                        @code{.desc @var{symbol}, @var{abs-expression}}
2928 @end ifset
2929 @ifset COFF
2930 * Dim::                         @code{.dim}
2931 @end ifset
2932
2933 * Double::                      @code{.double @var{flonums}}
2934 * Eject::                       @code{.eject}
2935 * Else::                        @code{.else}
2936 @ifset COFF
2937 * Endef::                       @code{.endef}
2938 @end ifset
2939
2940 * Endif::                       @code{.endif}
2941 * Equ::                         @code{.equ @var{symbol}, @var{expression}}
2942 * Equiv::                       @code{.equiv @var{symbol}, @var{expression}}
2943 * Err::                         @code{.err}
2944 * Extern::                      @code{.extern}
2945 @ifclear no-file-dir
2946 * File::                        @code{.file @var{string}}
2947 @end ifclear
2948
2949 * Fill::                        @code{.fill @var{repeat} , @var{size} , @var{value}}
2950 * Float::                       @code{.float @var{flonums}}
2951 * Global::                      @code{.global @var{symbol}}, @code{.globl @var{symbol}}
2952 * hword::                       @code{.hword @var{expressions}}
2953 * Ident::                       @code{.ident}
2954 * If::                          @code{.if @var{absolute expression}}
2955 * Include::                     @code{.include "@var{file}"}
2956 * Int::                         @code{.int @var{expressions}}
2957 * Irp::                         @code{.irp @var{symbol},@var{values}}@dots{}
2958 * Irpc::                        @code{.irpc @var{symbol},@var{values}}@dots{}
2959 * Lcomm::                       @code{.lcomm @var{symbol} , @var{length}}
2960 * Lflags::                      @code{.lflags}
2961 @ifclear no-line-dir
2962 * Line::                        @code{.line @var{line-number}}
2963 @end ifclear
2964
2965 * Ln::                          @code{.ln @var{line-number}}
2966 * Linkonce::                    @code{.linkonce [@var{type}]}
2967 * List::                        @code{.list}
2968 * Long::                        @code{.long @var{expressions}}
2969 @ignore
2970 * Lsym::                        @code{.lsym @var{symbol}, @var{expression}}
2971 @end ignore
2972
2973 * Macro::                       @code{.macro @var{name} @var{args}}@dots{}
2974 * MRI::                         @code{.mri @var{val}}
2975
2976 * Nolist::                      @code{.nolist}
2977 * Octa::                        @code{.octa @var{bignums}}
2978 * Org::                         @code{.org @var{new-lc} , @var{fill}}
2979 * P2align::                     @code{.p2align @var{abs-expr} , @var{abs-expr}}
2980 * Psize::                       @code{.psize @var{lines}, @var{columns}}
2981 * Quad::                        @code{.quad @var{bignums}}
2982 * Rept::                        @code{.rept @var{count}}
2983 * Sbttl::                       @code{.sbttl "@var{subheading}"}
2984 @ifset COFF
2985 * Scl::                         @code{.scl @var{class}}
2986 @end ifset
2987 @ifset COFF
2988 * Section::                     @code{.section @var{name}, @var{subsection}}
2989 @end ifset
2990
2991 * Set::                         @code{.set @var{symbol}, @var{expression}}
2992 * Short::                       @code{.short @var{expressions}}
2993 * Single::                      @code{.single @var{flonums}}
2994 @ifset COFF
2995 * Size::                        @code{.size}
2996 @end ifset
2997
2998 * Skip::                        @code{.skip @var{size} , @var{fill}}
2999 * Space::                       @code{.space @var{size} , @var{fill}}
3000 @ifset have-stabs
3001 * Stab::                        @code{.stabd, .stabn, .stabs}
3002 @end ifset
3003
3004 * String::                      @code{.string "@var{str}"}
3005 @ifset ELF
3006 * Symver::                      @code{.symver @var{name},@var{name2@@nodename}}
3007 @end ifset
3008 @ifset COFF
3009 * Tag::                         @code{.tag @var{structname}}
3010 @end ifset
3011
3012 * Text::                        @code{.text @var{subsection}}
3013 * Title::                       @code{.title "@var{heading}"}
3014 @ifset COFF
3015 * Type::                        @code{.type @var{int}}
3016 * Val::                         @code{.val @var{addr}}
3017 @end ifset
3018
3019 * Word::                        @code{.word @var{expressions}}
3020 * Deprecated::                  Deprecated Directives
3021 @end menu
3022
3023 @node Abort
3024 @section @code{.abort}
3025
3026 @cindex @code{abort} directive
3027 @cindex stopping the assembly
3028 This directive stops the assembly immediately.  It is for
3029 compatibility with other assemblers.  The original idea was that the
3030 assembly language source would be piped into the assembler.  If the sender
3031 of the source quit, it could use this directive tells @code{@value{AS}} to
3032 quit also.  One day @code{.abort} will not be supported.
3033
3034 @ifset COFF
3035 @node ABORT
3036 @section @code{.ABORT}
3037
3038 @cindex @code{ABORT} directive
3039 When producing COFF output, @code{@value{AS}} accepts this directive as a
3040 synonym for @samp{.abort}.
3041
3042 @ifset BOUT
3043 When producing @code{b.out} output, @code{@value{AS}} accepts this directive,
3044 but ignores it.
3045 @end ifset
3046 @end ifset
3047
3048 @node Align
3049 @section @code{.align @var{abs-expr}, @var{abs-expr}, @var{abs-expr}}
3050
3051 @cindex padding the location counter
3052 @cindex @code{align} directive
3053 Pad the location counter (in the current subsection) to a particular storage
3054 boundary.  The first expression (which must be absolute) is the alignment
3055 required, as described below.
3056
3057 The second expression (also absolute) gives the fill value to be stored in the
3058 padding bytes.  It (and the comma) may be omitted.  If it is omitted, the
3059 padding bytes are normally zero.  However, on some systems, if the section is
3060 marked as containing code and the fill value is omitted, the space is filled
3061 with no-op instructions.
3062
3063 The third expression is also absolute, and is also optional.  If it is present,
3064 it is the maximum number of bytes that should be skipped by this alignment
3065 directive.  If doing the alignment would require skipping more bytes than the
3066 specified maximum, then the alignment is not done at all.  You can omit the
3067 fill value (the second argument) entirely by simply using two commas after the
3068 required alignment; this can be useful if you want the alignment to be filled
3069 with no-op instructions when appropriate.
3070
3071 The way the required alignment is specified varies from system to system.
3072 For the a29k, hppa, m68k, m88k, w65, sparc, and Hitachi SH, and i386 using ELF
3073 format,
3074 the first expression is the
3075 alignment request in bytes.  For example @samp{.align 8} advances
3076 the location counter until it is a multiple of 8.  If the location counter
3077 is already a multiple of 8, no change is needed.
3078
3079 For other systems, including the i386 using a.out format, it is the
3080 number of low-order zero bits the location counter must have after
3081 advancement.  For example @samp{.align 3} advances the location
3082 counter until it a multiple of 8.  If the location counter is already a
3083 multiple of 8, no change is needed.
3084
3085 This inconsistency is due to the different behaviors of the various
3086 native assemblers for these systems which GAS must emulate.
3087 GAS also provides @code{.balign} and @code{.p2align} directives,
3088 described later, which have a consistent behavior across all
3089 architectures (but are specific to GAS).
3090
3091 @node App-File
3092 @section @code{.app-file @var{string}}
3093
3094 @cindex logical file name
3095 @cindex file name, logical
3096 @cindex @code{app-file} directive
3097 @code{.app-file}
3098 @ifclear no-file-dir
3099 (which may also be spelled @samp{.file})
3100 @end ifclear
3101 tells @code{@value{AS}} that we are about to start a new
3102 logical file.  @var{string} is the new file name.  In general, the
3103 filename is recognized whether or not it is surrounded by quotes @samp{"};
3104 but if you wish to specify an empty file name is permitted,
3105 you must give the quotes--@code{""}.  This statement may go away in
3106 future: it is only recognized to be compatible with old @code{@value{AS}}
3107 programs.@refill
3108
3109 @node Ascii
3110 @section @code{.ascii "@var{string}"}@dots{}
3111
3112 @cindex @code{ascii} directive
3113 @cindex string literals
3114 @code{.ascii} expects zero or more string literals (@pxref{Strings})
3115 separated by commas.  It assembles each string (with no automatic
3116 trailing zero byte) into consecutive addresses.
3117
3118 @node Asciz
3119 @section @code{.asciz "@var{string}"}@dots{}
3120
3121 @cindex @code{asciz} directive
3122 @cindex zero-terminated strings
3123 @cindex null-terminated strings
3124 @code{.asciz} is just like @code{.ascii}, but each string is followed by
3125 a zero byte.  The ``z'' in @samp{.asciz} stands for ``zero''.
3126
3127 @node Balign
3128 @section @code{.balign[wl] @var{abs-expr}, @var{abs-expr}, @var{abs-expr}}
3129
3130 @cindex padding the location counter given number of bytes
3131 @cindex @code{balign} directive
3132 Pad the location counter (in the current subsection) to a particular
3133 storage boundary.  The first expression (which must be absolute) is the
3134 alignment request in bytes.  For example @samp{.balign 8} advances
3135 the location counter until it is a multiple of 8.  If the location counter
3136 is already a multiple of 8, no change is needed.
3137
3138 The second expression (also absolute) gives the fill value to be stored in the
3139 padding bytes.  It (and the comma) may be omitted.  If it is omitted, the
3140 padding bytes are normally zero.  However, on some systems, if the section is
3141 marked as containing code and the fill value is omitted, the space is filled
3142 with no-op instructions.
3143
3144 The third expression is also absolute, and is also optional.  If it is present,
3145 it is the maximum number of bytes that should be skipped by this alignment
3146 directive.  If doing the alignment would require skipping more bytes than the
3147 specified maximum, then the alignment is not done at all.  You can omit the
3148 fill value (the second argument) entirely by simply using two commas after the
3149 required alignment; this can be useful if you want the alignment to be filled
3150 with no-op instructions when appropriate.
3151
3152 @cindex @code{balignw} directive
3153 @cindex @code{balignl} directive
3154 The @code{.balignw} and @code{.balignl} directives are variants of the
3155 @code{.balign} directive.  The @code{.balignw} directive treats the fill
3156 pattern as a two byte word value.  The @code{.balignl} directives treats the
3157 fill pattern as a four byte longword value.  For example, @code{.balignw
3158 4,0x368d} will align to a multiple of 4.  If it skips two bytes, they will be
3159 filled in with the value 0x368d (the exact placement of the bytes depends upon
3160 the endianness of the processor).  If it skips 1 or 3 bytes, the fill value is
3161 undefined.
3162
3163 @node Byte
3164 @section @code{.byte @var{expressions}}
3165
3166 @cindex @code{byte} directive
3167 @cindex integers, one byte
3168 @code{.byte} expects zero or more expressions, separated by commas.
3169 Each expression is assembled into the next byte.
3170
3171 @node Comm
3172 @section @code{.comm @var{symbol} , @var{length} }
3173
3174 @cindex @code{comm} directive
3175 @cindex symbol, common
3176 @code{.comm} declares a common symbol named @var{symbol}.  When linking, a
3177 common symbol in one object file may be merged with a defined or common symbol
3178 of the same name in another object file.  If @code{@value{LD}} does not see a
3179 definition for the symbol--just one or more common symbols--then it will
3180 allocate @var{length} bytes of uninitialized memory.  @var{length} must be an
3181 absolute expression.  If @code{@value{LD}} sees multiple common symbols with
3182 the same name, and they do not all have the same size, it will allocate space
3183 using the largest size.
3184
3185 @ifset ELF
3186 When using ELF, the @code{.comm} directive takes an optional third argument.
3187 This is the desired alignment of the symbol, specified as a byte boundary (for
3188 example, an alignment of 16 means that the least significant 4 bits of the
3189 address should be zero).  The alignment must be an absolute expression, and it
3190 must be a power of two.  If @code{@value{LD}} allocates uninitialized memory
3191 for the common symbol, it will use the alignment when placing the symbol.  If
3192 no alignment is specified, @code{@value{AS}} will set the alignment to the
3193 largest power of two less than or equal to the size of the symbol, up to a
3194 maximum of 16.
3195 @end ifset
3196
3197 @ifset HPPA
3198 The syntax for @code{.comm} differs slightly on the HPPA.  The syntax is
3199 @samp{@var{symbol} .comm, @var{length}}; @var{symbol} is optional.
3200 @end ifset
3201
3202 @node Data
3203 @section @code{.data @var{subsection}}
3204
3205 @cindex @code{data} directive
3206 @code{.data} tells @code{@value{AS}} to assemble the following statements onto the
3207 end of the data subsection numbered @var{subsection} (which is an
3208 absolute expression).  If @var{subsection} is omitted, it defaults
3209 to zero.
3210
3211 @ifset COFF
3212 @node Def
3213 @section @code{.def @var{name}}
3214
3215 @cindex @code{def} directive
3216 @cindex COFF symbols, debugging
3217 @cindex debugging COFF symbols
3218 Begin defining debugging information for a symbol @var{name}; the
3219 definition extends until the @code{.endef} directive is encountered.
3220 @ifset BOUT
3221
3222 This directive is only observed when @code{@value{AS}} is configured for COFF
3223 format output; when producing @code{b.out}, @samp{.def} is recognized,
3224 but ignored.
3225 @end ifset
3226 @end ifset
3227
3228 @ifset aout-bout
3229 @node Desc
3230 @section @code{.desc @var{symbol}, @var{abs-expression}}
3231
3232 @cindex @code{desc} directive
3233 @cindex COFF symbol descriptor
3234 @cindex symbol descriptor, COFF
3235 This directive sets the descriptor of the symbol (@pxref{Symbol Attributes})
3236 to the low 16 bits of an absolute expression.
3237
3238 @ifset COFF
3239 The @samp{.desc} directive is not available when @code{@value{AS}} is
3240 configured for COFF output; it is only for @code{a.out} or @code{b.out}
3241 object format.  For the sake of compatibility, @code{@value{AS}} accepts
3242 it, but produces no output, when configured for COFF.
3243 @end ifset
3244 @end ifset
3245
3246 @ifset COFF
3247 @node Dim
3248 @section @code{.dim}
3249
3250 @cindex @code{dim} directive
3251 @cindex COFF auxiliary symbol information
3252 @cindex auxiliary symbol information, COFF
3253 This directive is generated by compilers to include auxiliary debugging
3254 information in the symbol table.  It is only permitted inside
3255 @code{.def}/@code{.endef} pairs.
3256 @ifset BOUT
3257
3258 @samp{.dim} is only meaningful when generating COFF format output; when
3259 @code{@value{AS}} is generating @code{b.out}, it accepts this directive but
3260 ignores it.
3261 @end ifset
3262 @end ifset
3263
3264 @node Double
3265 @section @code{.double @var{flonums}}
3266
3267 @cindex @code{double} directive
3268 @cindex floating point numbers (double)
3269 @code{.double} expects zero or more flonums, separated by commas.  It
3270 assembles floating point numbers.
3271 @ifset GENERIC
3272 The exact kind of floating point numbers emitted depends on how
3273 @code{@value{AS}} is configured.  @xref{Machine Dependencies}.
3274 @end ifset
3275 @ifclear GENERIC
3276 @ifset IEEEFLOAT
3277 On the @value{TARGET} family @samp{.double} emits 64-bit floating-point numbers
3278 in @sc{ieee} format.
3279 @end ifset
3280 @end ifclear
3281
3282 @node Eject
3283 @section @code{.eject}
3284
3285 @cindex @code{eject} directive
3286 @cindex new page, in listings
3287 @cindex page, in listings
3288 @cindex listing control: new page
3289 Force a page break at this point, when generating assembly listings.
3290
3291 @node Else
3292 @section @code{.else}
3293
3294 @cindex @code{else} directive
3295 @code{.else} is part of the @code{@value{AS}} support for conditional
3296 assembly; @pxref{If,,@code{.if}}.  It marks the beginning of a section
3297 of code to be assembled if the condition for the preceding @code{.if}
3298 was false.
3299
3300 @ignore
3301 @node End, Endef, Else, Pseudo Ops
3302 @section @code{.end}
3303
3304 @cindex @code{end} directive
3305 This doesn't do anything---but isn't an s_ignore, so I suspect it's
3306 meant to do something eventually (which is why it isn't documented here
3307 as "for compatibility with blah").
3308 @end ignore
3309
3310 @ifset COFF
3311 @node Endef
3312 @section @code{.endef}
3313
3314 @cindex @code{endef} directive
3315 This directive flags the end of a symbol definition begun with
3316 @code{.def}.
3317 @ifset BOUT
3318
3319 @samp{.endef} is only meaningful when generating COFF format output; if
3320 @code{@value{AS}} is configured to generate @code{b.out}, it accepts this
3321 directive but ignores it.
3322 @end ifset
3323 @end ifset
3324
3325 @node Endif
3326 @section @code{.endif}
3327
3328 @cindex @code{endif} directive
3329 @code{.endif} is part of the @code{@value{AS}} support for conditional assembly;
3330 it marks the end of a block of code that is only assembled
3331 conditionally.  @xref{If,,@code{.if}}.
3332
3333 @node Equ
3334 @section @code{.equ @var{symbol}, @var{expression}}
3335
3336 @cindex @code{equ} directive
3337 @cindex assigning values to symbols
3338 @cindex symbols, assigning values to
3339 This directive sets the value of @var{symbol} to @var{expression}.
3340 It is synonymous with @samp{.set}; @pxref{Set,,@code{.set}}.
3341
3342 @ifset HPPA
3343 The syntax for @code{equ} on the HPPA is 
3344 @samp{@var{symbol} .equ @var{expression}}.
3345 @end ifset
3346
3347 @node Equiv
3348 @section @code{.equiv @var{symbol}, @var{expression}}
3349 @cindex @code{equiv} directive
3350 The @code{.equiv} directive is like @code{.equ} and @code{.set}, except that
3351 the assembler will signal an error if @var{symbol} is already defined.
3352
3353 Except for the contents of the error message, this is roughly equivalent to 
3354 @smallexample
3355 .ifdef SYM
3356 .err
3357 .endif
3358 .equ SYM,VAL
3359 @end smallexample
3360
3361 @node Err
3362 @section @code{.err}
3363 @cindex @code{err} directive
3364 If @code{@value{AS}} assembles a @code{.err} directive, it will print an error
3365 message and, unless the @code{-Z} option was used, it will not generate an
3366 object file.  This can be used to signal error an conditionally compiled code.
3367
3368 @node Extern
3369 @section @code{.extern}
3370
3371 @cindex @code{extern} directive
3372 @code{.extern} is accepted in the source program---for compatibility
3373 with other assemblers---but it is ignored.  @code{@value{AS}} treats
3374 all undefined symbols as external.
3375
3376 @ifclear no-file-dir
3377 @node File
3378 @section @code{.file @var{string}}
3379
3380 @cindex @code{file} directive
3381 @cindex logical file name
3382 @cindex file name, logical
3383 @code{.file} (which may also be spelled @samp{.app-file}) tells
3384 @code{@value{AS}} that we are about to start a new logical file.
3385 @var{string} is the new file name.  In general, the filename is
3386 recognized whether or not it is surrounded by quotes @samp{"}; but if
3387 you wish to specify an empty file name, you must give the
3388 quotes--@code{""}.  This statement may go away in future: it is only
3389 recognized to be compatible with old @code{@value{AS}} programs.
3390 @ifset A29K
3391 In some configurations of @code{@value{AS}}, @code{.file} has already been
3392 removed to avoid conflicts with other assemblers.  @xref{Machine Dependencies}.
3393 @end ifset
3394 @end ifclear
3395
3396 @node Fill
3397 @section @code{.fill @var{repeat} , @var{size} , @var{value}}
3398
3399 @cindex @code{fill} directive
3400 @cindex writing patterns in memory
3401 @cindex patterns, writing in memory
3402 @var{result}, @var{size} and @var{value} are absolute expressions.
3403 This emits @var{repeat} copies of @var{size} bytes.  @var{Repeat}
3404 may be zero or more.  @var{Size} may be zero or more, but if it is
3405 more than 8, then it is deemed to have the value 8, compatible with
3406 other people's assemblers.  The contents of each @var{repeat} bytes
3407 is taken from an 8-byte number.  The highest order 4 bytes are
3408 zero.  The lowest order 4 bytes are @var{value} rendered in the
3409 byte-order of an integer on the computer @code{@value{AS}} is assembling for.
3410 Each @var{size} bytes in a repetition is taken from the lowest order
3411 @var{size} bytes of this number.  Again, this bizarre behavior is
3412 compatible with other people's assemblers.
3413
3414 @var{size} and @var{value} are optional.
3415 If the second comma and @var{value} are absent, @var{value} is
3416 assumed zero.  If the first comma and following tokens are absent,
3417 @var{size} is assumed to be 1.
3418
3419 @node Float
3420 @section @code{.float @var{flonums}}
3421
3422 @cindex floating point numbers (single)
3423 @cindex @code{float} directive
3424 This directive assembles zero or more flonums, separated by commas.  It
3425 has the same effect as @code{.single}.
3426 @ifset GENERIC
3427 The exact kind of floating point numbers emitted depends on how
3428 @code{@value{AS}} is configured.
3429 @xref{Machine Dependencies}.
3430 @end ifset
3431 @ifclear GENERIC
3432 @ifset IEEEFLOAT
3433 On the @value{TARGET} family, @code{.float} emits 32-bit floating point numbers
3434 in @sc{ieee} format.
3435 @end ifset
3436 @end ifclear
3437
3438 @node Global
3439 @section @code{.global @var{symbol}}, @code{.globl @var{symbol}}
3440
3441 @cindex @code{global} directive
3442 @cindex symbol, making visible to linker
3443 @code{.global} makes the symbol visible to @code{@value{LD}}.  If you define
3444 @var{symbol} in your partial program, its value is made available to
3445 other partial programs that are linked with it.  Otherwise,
3446 @var{symbol} takes its attributes from a symbol of the same name
3447 from another file linked into the same program.
3448
3449 Both spellings (@samp{.globl} and @samp{.global}) are accepted, for
3450 compatibility with other assemblers.
3451
3452 @ifset HPPA
3453 On the HPPA, @code{.global} is not always enough to make it accessible to other
3454 partial programs.  You may need the HPPA-only @code{.EXPORT} directive as well.
3455 @xref{HPPA Directives,, HPPA Assembler Directives}.
3456 @end ifset
3457
3458 @node hword
3459 @section @code{.hword @var{expressions}}
3460
3461 @cindex @code{hword} directive
3462 @cindex integers, 16-bit
3463 @cindex numbers, 16-bit
3464 @cindex sixteen bit integers
3465 This expects zero or more @var{expressions}, and emits
3466 a 16 bit number for each.
3467
3468 @ifset GENERIC
3469 This directive is a synonym for @samp{.short}; depending on the target
3470 architecture, it may also be a synonym for @samp{.word}.
3471 @end ifset
3472 @ifclear GENERIC
3473 @ifset W32
3474 This directive is a synonym for @samp{.short}.
3475 @end ifset
3476 @ifset W16
3477 This directive is a synonym for both @samp{.short} and @samp{.word}.
3478 @end ifset
3479 @end ifclear
3480
3481 @node Ident
3482 @section @code{.ident}
3483
3484 @cindex @code{ident} directive
3485 This directive is used by some assemblers to place tags in object files.
3486 @code{@value{AS}} simply accepts the directive for source-file
3487 compatibility with such assemblers, but does not actually emit anything
3488 for it.
3489
3490 @node If
3491 @section @code{.if @var{absolute expression}}
3492
3493 @cindex conditional assembly
3494 @cindex @code{if} directive
3495 @code{.if} marks the beginning of a section of code which is only
3496 considered part of the source program being assembled if the argument
3497 (which must be an @var{absolute expression}) is non-zero.  The end of
3498 the conditional section of code must be marked by @code{.endif}
3499 (@pxref{Endif,,@code{.endif}}); optionally, you may include code for the
3500 alternative condition, flagged by @code{.else} (@pxref{Else,,@code{.else}}).
3501
3502 The following variants of @code{.if} are also supported:
3503 @table @code
3504 @cindex @code{ifdef} directive
3505 @item .ifdef @var{symbol}
3506 Assembles the following section of code if the specified @var{symbol}
3507 has been defined.
3508
3509 @ignore
3510 @cindex @code{ifeqs} directive
3511 @item .ifeqs
3512 Not yet implemented.
3513 @end ignore
3514
3515 @cindex @code{ifndef} directive
3516 @cindex @code{ifnotdef} directive
3517 @item .ifndef @var{symbol}
3518 @itemx .ifnotdef @var{symbol}
3519 Assembles the following section of code if the specified @var{symbol}
3520 has not been defined.  Both spelling variants are equivalent.
3521
3522 @ignore
3523 @item ifnes
3524 Not yet implemented.
3525 @end ignore
3526 @end table
3527
3528 @node Include
3529 @section @code{.include "@var{file}"}
3530
3531 @cindex @code{include} directive
3532 @cindex supporting files, including
3533 @cindex files, including
3534 This directive provides a way to include supporting files at specified
3535 points in your source program.  The code from @var{file} is assembled as
3536 if it followed the point of the @code{.include}; when the end of the
3537 included file is reached, assembly of the original file continues.  You
3538 can control the search paths used with the @samp{-I} command-line option
3539 (@pxref{Invoking,,Command-Line Options}).  Quotation marks are required
3540 around @var{file}.
3541
3542 @node Int
3543 @section @code{.int @var{expressions}}
3544
3545 @cindex @code{int} directive
3546 @cindex integers, 32-bit
3547 Expect zero or more @var{expressions}, of any section, separated by commas.
3548 For each expression, emit a number that, at run time, is the value of that
3549 expression.  The byte order and bit size of the number depends on what kind
3550 of target the assembly is for.
3551
3552 @ifclear GENERIC
3553 @ifset H8
3554 On the H8/500 and most forms of the H8/300, @code{.int} emits 16-bit
3555 integers.  On the H8/300H and the Hitachi SH, however, @code{.int} emits
3556 32-bit integers.
3557 @end ifset
3558 @end ifclear
3559
3560 @node Irp
3561 @section @code{.irp @var{symbol},@var{values}}@dots{}
3562
3563 @cindex @code{irp} directive
3564 Evaluate a sequence of statements assigning different values to @var{symbol}.
3565 The sequence of statements starts at the @code{.irp} directive, and is
3566 terminated by an @code{.endr} directive.  For each @var{value}, @var{symbol} is
3567 set to @var{value}, and the sequence of statements is assembled.  If no
3568 @var{value} is listed, the sequence of statements is assembled once, with
3569 @var{symbol} set to the null string.  To refer to @var{symbol} within the
3570 sequence of statements, use @var{\symbol}.
3571
3572 For example, assembling
3573
3574 @example
3575         .irp    param,1,2,3
3576         move    d\param,sp@@-
3577         .endr
3578 @end example
3579
3580 is equivalent to assembling
3581
3582 @example
3583         move    d1,sp@@-
3584         move    d2,sp@@-
3585         move    d3,sp@@-
3586 @end example
3587
3588 @node Irpc
3589 @section @code{.irpc @var{symbol},@var{values}}@dots{}
3590
3591 @cindex @code{irpc} directive
3592 Evaluate a sequence of statements assigning different values to @var{symbol}.
3593 The sequence of statements starts at the @code{.irpc} directive, and is
3594 terminated by an @code{.endr} directive.  For each character in @var{value},
3595 @var{symbol} is set to the character, and the sequence of statements is
3596 assembled.  If no @var{value} is listed, the sequence of statements is
3597 assembled once, with @var{symbol} set to the null string.  To refer to
3598 @var{symbol} within the sequence of statements, use @var{\symbol}.
3599
3600 For example, assembling
3601
3602 @example
3603         .irpc    param,123
3604         move    d\param,sp@@-
3605         .endr
3606 @end example
3607
3608 is equivalent to assembling
3609
3610 @example
3611         move    d1,sp@@-
3612         move    d2,sp@@-
3613         move    d3,sp@@-
3614 @end example
3615
3616 @node Lcomm
3617 @section @code{.lcomm @var{symbol} , @var{length}}
3618
3619 @cindex @code{lcomm} directive
3620 @cindex local common symbols
3621 @cindex symbols, local common
3622 Reserve @var{length} (an absolute expression) bytes for a local common
3623 denoted by @var{symbol}.  The section and value of @var{symbol} are
3624 those of the new local common.  The addresses are allocated in the bss
3625 section, so that at run-time the bytes start off zeroed.  @var{Symbol}
3626 is not declared global (@pxref{Global,,@code{.global}}), so is normally
3627 not visible to @code{@value{LD}}.
3628
3629 @ifset GENERIC
3630 Some targets permit a third argument to be used with @code{.lcomm}.  This
3631 argument specifies the desired alignment of the symbol in the bss section.
3632 @end ifset
3633
3634 @ifset HPPA
3635 The syntax for @code{.lcomm} differs slightly on the HPPA.  The syntax is
3636 @samp{@var{symbol} .lcomm, @var{length}}; @var{symbol} is optional.
3637 @end ifset
3638
3639 @node Lflags
3640 @section @code{.lflags}
3641
3642 @cindex @code{lflags} directive (ignored)
3643 @code{@value{AS}} accepts this directive, for compatibility with other
3644 assemblers, but ignores it.
3645
3646 @ifclear no-line-dir
3647 @node Line
3648 @section @code{.line @var{line-number}}
3649
3650 @cindex @code{line} directive
3651 @end ifclear
3652 @ifset no-line-dir
3653 @node Ln
3654 @section @code{.ln @var{line-number}}
3655
3656 @cindex @code{ln} directive
3657 @end ifset
3658 @cindex logical line number
3659 @ifset aout-bout
3660 Change the logical line number.  @var{line-number} must be an absolute
3661 expression.  The next line has that logical line number.  Therefore any other
3662 statements on the current line (after a statement separator character) are
3663 reported as on logical line number @var{line-number} @minus{} 1.  One day
3664 @code{@value{AS}} will no longer support this directive: it is recognized only
3665 for compatibility with existing assembler programs.
3666
3667 @ifset GENERIC
3668 @ifset A29K
3669 @emph{Warning:} In the AMD29K configuration of @value{AS}, this command is
3670 not available; use the synonym @code{.ln} in that context.
3671 @end ifset
3672 @end ifset
3673 @end ifset
3674
3675 @ifclear no-line-dir
3676 Even though this is a directive associated with the @code{a.out} or
3677 @code{b.out} object-code formats, @code{@value{AS}} still recognizes it
3678 when producing COFF output, and treats @samp{.line} as though it
3679 were the COFF @samp{.ln} @emph{if} it is found outside a
3680 @code{.def}/@code{.endef} pair.
3681
3682 Inside a @code{.def}, @samp{.line} is, instead, one of the directives
3683 used by compilers to generate auxiliary symbol information for
3684 debugging.
3685 @end ifclear
3686
3687 @node Linkonce
3688 @section @code{.linkonce [@var{type}]}
3689 @cindex COMDAT
3690 @cindex @code{linkonce} directive
3691 @cindex common sections
3692 Mark the current section so that the linker only includes a single copy of it.
3693 This may be used to include the same section in several different object files,
3694 but ensure that the linker will only include it once in the final output file.
3695 The @code{.linkonce} pseudo-op must be used for each instance of the section.
3696 Duplicate sections are detected based on the section name, so it should be
3697 unique.
3698
3699 This directive is only supported by a few object file formats; as of this
3700 writing, the only object file format which supports it is the Portable
3701 Executable format used on Windows NT.
3702
3703 The @var{type} argument is optional.  If specified, it must be one of the
3704 following strings.  For example:
3705 @smallexample
3706 .linkonce same_size
3707 @end smallexample
3708 Not all types may be supported on all object file formats.
3709
3710 @table @code
3711 @item discard
3712 Silently discard duplicate sections.  This is the default.
3713
3714 @item one_only
3715 Warn if there are duplicate sections, but still keep only one copy.
3716
3717 @item same_size
3718 Warn if any of the duplicates have different sizes.
3719
3720 @item same_contents
3721 Warn if any of the duplicates do not have exactly the same contents.
3722 @end table
3723
3724 @node Ln
3725 @section @code{.ln @var{line-number}}
3726
3727 @cindex @code{ln} directive
3728 @ifclear no-line-dir
3729 @samp{.ln} is a synonym for @samp{.line}.
3730 @end ifclear
3731 @ifset no-line-dir
3732 Tell @code{@value{AS}} to change the logical line number.  @var{line-number}
3733 must be an absolute expression.  The next line has that logical
3734 line number, so any other statements on the current line (after a
3735 statement separator character @code{;}) are reported as on logical
3736 line number @var{line-number} @minus{} 1.
3737 @ifset BOUT
3738
3739 This directive is accepted, but ignored, when @code{@value{AS}} is
3740 configured for @code{b.out}; its effect is only associated with COFF
3741 output format.
3742 @end ifset
3743 @end ifset
3744
3745 @node MRI
3746 @section @code{.mri @var{val}}
3747
3748 @cindex @code{mri} directive
3749 @cindex MRI mode, temporarily
3750 If @var{val} is non-zero, this tells @code{@value{AS}} to enter MRI mode.  If
3751 @var{val} is zero, this tells @code{@value{AS}} to exit MRI mode.  This change
3752 affects code assembled until the next @code{.mri} directive, or until the end
3753 of the file.  @xref{M, MRI mode, MRI mode}.
3754
3755 @node List
3756 @section @code{.list}
3757
3758 @cindex @code{list} directive
3759 @cindex listing control, turning on
3760 Control (in conjunction with the @code{.nolist} directive) whether or
3761 not assembly listings are generated.  These two directives maintain an
3762 internal counter (which is zero initially).   @code{.list} increments the
3763 counter, and @code{.nolist} decrements it.  Assembly listings are
3764 generated whenever the counter is greater than zero.
3765
3766 By default, listings are disabled.  When you enable them (with the
3767 @samp{-a} command line option; @pxref{Invoking,,Command-Line Options}),
3768 the initial value of the listing counter is one.
3769
3770 @node Long
3771 @section @code{.long @var{expressions}}
3772
3773 @cindex @code{long} directive
3774 @code{.long} is the same as @samp{.int}, @pxref{Int,,@code{.int}}.
3775
3776 @ignore
3777 @c no one seems to know what this is for or whether this description is
3778 @c what it really ought to do
3779 @node Lsym
3780 @section @code{.lsym @var{symbol}, @var{expression}}
3781
3782 @cindex @code{lsym} directive
3783 @cindex symbol, not referenced in assembly
3784 @code{.lsym} creates a new symbol named @var{symbol}, but does not put it in
3785 the hash table, ensuring it cannot be referenced by name during the
3786 rest of the assembly.  This sets the attributes of the symbol to be
3787 the same as the expression value:
3788 @smallexample
3789 @var{other} = @var{descriptor} = 0
3790 @var{type} = @r{(section of @var{expression})}
3791 @var{value} = @var{expression}
3792 @end smallexample
3793 @noindent
3794 The new symbol is not flagged as external.
3795 @end ignore
3796
3797 @node Macro
3798 @section @code{.macro}
3799
3800 @cindex macros
3801 The commands @code{.macro} and @code{.endm} allow you to define macros that
3802 generate assembly output.  For example, this definition specifies a macro
3803 @code{sum} that puts a sequence of numbers into memory:
3804
3805 @example
3806         .macro  sum from=0, to=5
3807         .long   \from
3808         .if     \to-\from
3809         sum     "(\from+1)",\to
3810         .endif
3811         .endm
3812 @end example
3813
3814 @noindent
3815 With that definition, @samp{SUM 0,5} is equivalent to this assembly input:
3816
3817 @example
3818         .long   0
3819         .long   1
3820         .long   2
3821         .long   3
3822         .long   4
3823         .long   5
3824 @end example
3825
3826 @ftable @code
3827 @item .macro @var{macname}
3828 @itemx .macro @var{macname} @var{macargs} @dots{}
3829 @cindex @code{macro} directive
3830 Begin the definition of a macro called @var{macname}.  If your macro
3831 definition requires arguments, specify their names after the macro name,
3832 separated by commas or spaces.  You can supply a default value for any
3833 macro argument by following the name with @samp{=@var{deflt}}.  For
3834 example, these are all valid @code{.macro} statements:
3835
3836 @table @code
3837 @item .macro comm
3838 Begin the definition of a macro called @code{comm}, which takes no
3839 arguments.
3840
3841 @item .macro plus1 p, p1
3842 @itemx .macro plus1 p p1
3843 Either statement begins the definition of a macro called @code{plus1},
3844 which takes two arguments; within the macro definition, write
3845 @samp{\p} or @samp{\p1} to evaluate the arguments.
3846
3847 @item .macro reserve_str p1=0 p2
3848 Begin the definition of a macro called @code{reserve_str}, with two
3849 arguments.  The first argument has a default value, but not the second.
3850 After the definition is complete, you can call the macro either as
3851 @samp{reserve_str @var{a},@var{b}} (with @samp{\p1} evaluating to
3852 @var{a} and @samp{\p2} evaluating to @var{b}), or as @samp{reserve_str
3853 ,@var{b}} (with @samp{\p1} evaluating as the default, in this case
3854 @samp{0}, and @samp{\p2} evaluating to @var{b}).
3855 @end table
3856
3857 When you call a macro, you can specify the argument values either by
3858 position, or by keyword.  For example, @samp{sum 9,17} is equivalent to
3859 @samp{sum to=17, from=9}.
3860
3861 @item .endm
3862 @cindex @code{endm} directive
3863 Mark the end of a macro definition.
3864
3865 @item .exitm
3866 @cindex @code{exitm} directive
3867 Exit early from the current macro definition.
3868
3869 @cindex number of macros executed
3870 @cindex macros, count executed
3871 @item \@@
3872 @code{@value{AS}} maintains a counter of how many macros it has
3873 executed in this pseudo-variable; you can copy that number to your
3874 output with @samp{\@@}, but @emph{only within a macro definition}.
3875
3876 @ignore
3877 @item LOCAL @var{name} [ , @dots{} ]
3878 @emph{Warning: @code{LOCAL} is only available if you select ``alternate
3879 macro syntax'' with @samp{-a} or @samp{--alternate}.}  @xref{Alternate,,
3880 Alternate macro syntax}.
3881
3882 Generate a string replacement for each of the @var{name} arguments, and
3883 replace any instances of @var{name} in each macro expansion.  The
3884 replacement string is unique in the assembly, and different for each
3885 separate macro expansion.  @code{LOCAL} allows you to write macros that
3886 define symbols, without fear of conflict between separate macro expansions.
3887 @end ignore
3888 @end ftable
3889
3890 @node Nolist
3891 @section @code{.nolist}
3892
3893 @cindex @code{nolist} directive
3894 @cindex listing control, turning off
3895 Control (in conjunction with the @code{.list} directive) whether or
3896 not assembly listings are generated.  These two directives maintain an
3897 internal counter (which is zero initially).   @code{.list} increments the
3898 counter, and @code{.nolist} decrements it.  Assembly listings are
3899 generated whenever the counter is greater than zero.
3900
3901 @node Octa
3902 @section @code{.octa @var{bignums}}
3903
3904 @c FIXME: double size emitted for "octa" on i960, others?  Or warn?
3905 @cindex @code{octa} directive
3906 @cindex integer, 16-byte
3907 @cindex sixteen byte integer
3908 This directive expects zero or more bignums, separated by commas.  For each
3909 bignum, it emits a 16-byte integer.
3910
3911 The term ``octa'' comes from contexts in which a ``word'' is two bytes;
3912 hence @emph{octa}-word for 16 bytes.
3913
3914 @node Org
3915 @section @code{.org @var{new-lc} , @var{fill}}
3916
3917 @cindex @code{org} directive
3918 @cindex location counter, advancing
3919 @cindex advancing location counter
3920 @cindex current address, advancing
3921 Advance the location counter of the current section to
3922 @var{new-lc}.  @var{new-lc} is either an absolute expression or an
3923 expression with the same section as the current subsection.  That is,
3924 you can't use @code{.org} to cross sections: if @var{new-lc} has the
3925 wrong section, the @code{.org} directive is ignored.  To be compatible
3926 with former assemblers, if the section of @var{new-lc} is absolute,
3927 @code{@value{AS}} issues a warning, then pretends the section of @var{new-lc}
3928 is the same as the current subsection.
3929
3930 @code{.org} may only increase the location counter, or leave it
3931 unchanged; you cannot use @code{.org} to move the location counter
3932 backwards.
3933
3934 @c double negative used below "not undefined" because this is a specific
3935 @c reference to "undefined" (as SEG_UNKNOWN is called in this manual)
3936 @c section. doc@cygnus.com 18feb91
3937 Because @code{@value{AS}} tries to assemble programs in one pass, @var{new-lc}
3938 may not be undefined.  If you really detest this restriction we eagerly await
3939 a chance to share your improved assembler.
3940
3941 Beware that the origin is relative to the start of the section, not
3942 to the start of the subsection.  This is compatible with other
3943 people's assemblers.
3944
3945 When the location counter (of the current subsection) is advanced, the
3946 intervening bytes are filled with @var{fill} which should be an
3947 absolute expression.  If the comma and @var{fill} are omitted,
3948 @var{fill} defaults to zero.
3949
3950 @node P2align
3951 @section @code{.p2align[wl] @var{abs-expr}, @var{abs-expr}, @var{abs-expr}}
3952
3953 @cindex padding the location counter given a power of two
3954 @cindex @code{p2align} directive
3955 Pad the location counter (in the current subsection) to a particular
3956 storage boundary.  The first expression (which must be absolute) is the
3957 number of low-order zero bits the location counter must have after
3958 advancement.  For example @samp{.p2align 3} advances the location
3959 counter until it a multiple of 8.  If the location counter is already a
3960 multiple of 8, no change is needed.
3961
3962 The second expression (also absolute) gives the fill value to be stored in the
3963 padding bytes.  It (and the comma) may be omitted.  If it is omitted, the
3964 padding bytes are normally zero.  However, on some systems, if the section is
3965 marked as containing code and the fill value is omitted, the space is filled
3966 with no-op instructions.
3967
3968 The third expression is also absolute, and is also optional.  If it is present,
3969 it is the maximum number of bytes that should be skipped by this alignment
3970 directive.  If doing the alignment would require skipping more bytes than the
3971 specified maximum, then the alignment is not done at all.  You can omit the
3972 fill value (the second argument) entirely by simply using two commas after the
3973 required alignment; this can be useful if you want the alignment to be filled
3974 with no-op instructions when appropriate.
3975
3976 @cindex @code{p2alignw} directive
3977 @cindex @code{p2alignl} directive
3978 The @code{.p2alignw} and @code{.p2alignl} directives are variants of the
3979 @code{.p2align} directive.  The @code{.p2alignw} directive treats the fill
3980 pattern as a two byte word value.  The @code{.p2alignl} directives treats the
3981 fill pattern as a four byte longword value.  For example, @code{.p2alignw
3982 2,0x368d} will align to a multiple of 4.  If it skips two bytes, they will be
3983 filled in with the value 0x368d (the exact placement of the bytes depends upon
3984 the endianness of the processor).  If it skips 1 or 3 bytes, the fill value is
3985 undefined.
3986
3987 @node Psize
3988 @section @code{.psize @var{lines} , @var{columns}}
3989
3990 @cindex @code{psize} directive
3991 @cindex listing control: paper size
3992 @cindex paper size, for listings
3993 Use this directive to declare the number of lines---and, optionally, the
3994 number of columns---to use for each page, when generating listings.
3995
3996 If you do not use @code{.psize}, listings use a default line-count
3997 of 60.  You may omit the comma and @var{columns} specification; the
3998 default width is 200 columns.
3999
4000 @code{@value{AS}} generates formfeeds whenever the specified number of
4001 lines is exceeded (or whenever you explicitly request one, using
4002 @code{.eject}).
4003
4004 If you specify @var{lines} as @code{0}, no formfeeds are generated save
4005 those explicitly specified with @code{.eject}.
4006
4007 @node Quad
4008 @section @code{.quad @var{bignums}}
4009
4010 @cindex @code{quad} directive
4011 @code{.quad} expects zero or more bignums, separated by commas.  For
4012 each bignum, it emits
4013 @ifclear bignum-16
4014 an 8-byte integer.  If the bignum won't fit in 8 bytes, it prints a
4015 warning message; and just takes the lowest order 8 bytes of the bignum.
4016 @cindex eight-byte integer
4017 @cindex integer, 8-byte
4018
4019 The term ``quad'' comes from contexts in which a ``word'' is two bytes;
4020 hence @emph{quad}-word for 8 bytes.
4021 @end ifclear
4022 @ifset bignum-16
4023 a 16-byte integer.  If the bignum won't fit in 16 bytes, it prints a
4024 warning message; and just takes the lowest order 16 bytes of the bignum.
4025 @cindex sixteen-byte integer
4026 @cindex integer, 16-byte
4027 @end ifset
4028
4029 @node Rept
4030 @section @code{.rept @var{count}}
4031
4032 @cindex @code{rept} directive
4033 Repeat the sequence of lines between the @code{.rept} directive and the next
4034 @code{.endr} directive @var{count} times.
4035
4036 For example, assembling
4037
4038 @example
4039         .rept   3
4040         .long   0
4041         .endr
4042 @end example
4043
4044 is equivalent to assembling
4045
4046 @example
4047         .long   0
4048         .long   0
4049         .long   0
4050 @end example
4051
4052 @node Sbttl
4053 @section @code{.sbttl "@var{subheading}"}
4054
4055 @cindex @code{sbttl} directive
4056 @cindex subtitles for listings
4057 @cindex listing control: subtitle
4058 Use @var{subheading} as the title (third line, immediately after the
4059 title line) when generating assembly listings.
4060
4061 This directive affects subsequent pages, as well as the current page if
4062 it appears within ten lines of the top of a page.
4063
4064 @ifset COFF
4065 @node Scl
4066 @section @code{.scl @var{class}}
4067
4068 @cindex @code{scl} directive
4069 @cindex symbol storage class (COFF)
4070 @cindex COFF symbol storage class
4071 Set the storage-class value for a symbol.  This directive may only be
4072 used inside a @code{.def}/@code{.endef} pair.  Storage class may flag
4073 whether a symbol is static or external, or it may record further
4074 symbolic debugging information.
4075 @ifset BOUT
4076
4077 The @samp{.scl} directive is primarily associated with COFF output; when
4078 configured to generate @code{b.out} output format, @code{@value{AS}}
4079 accepts this directive but ignores it.
4080 @end ifset
4081 @end ifset
4082
4083 @node Section
4084 @section @code{.section @var{name}}
4085
4086 @cindex @code{section} directive
4087 @cindex named section
4088 Use the @code{.section} directive to assemble the following code into a section
4089 named @var{name}.
4090
4091 This directive is only supported for targets that actually support arbitrarily
4092 named sections; on @code{a.out} targets, for example, it is not accepted, even
4093 with a standard @code{a.out} section name.
4094
4095 @ifset COFF
4096 For COFF targets, the @code{.section} directive is used in one of the following
4097 ways:
4098 @smallexample
4099 .section @var{name}[, "@var{flags}"]
4100 .section @var{name}[, @var{subsegment}]
4101 @end smallexample
4102
4103 If the optional argument is quoted, it is taken as flags to use for the
4104 section.  Each flag is a single character.  The following flags are recognized:
4105 @table @code
4106 @item b
4107 bss section (uninitialized data)
4108 @item n
4109 section is not loaded
4110 @item w
4111 writable section
4112 @item d
4113 data section
4114 @item r
4115 read-only section
4116 @item x
4117 executable section
4118 @end table
4119
4120 If no flags are specified, the default flags depend upon the section name.  If
4121 the section name is not recognized, the default will be for the section to be
4122 loaded and writable.
4123
4124 If the optional argument to the @code{.section} directive is not quoted, it is
4125 taken as a subsegment number (@pxref{Sub-Sections}).
4126 @end ifset
4127
4128 @ifset ELF
4129 For ELF targets, the @code{.section} directive is used like this:
4130 @smallexample
4131 .section @var{name}[, "@var{flags}"[, @@@var{type}]]
4132 @end smallexample
4133 The optional @var{flags} argument is a quoted string which may contain any
4134 combintion of the following characters:
4135 @table @code
4136 @item a
4137 section is allocatable
4138 @item w
4139 section is writable
4140 @item x
4141 section is executable
4142 @end table
4143
4144 The optional @var{type} argument may contain one of the following constants:
4145 @table @code
4146 @item @@progbits
4147 section contains data
4148 @item @@nobits
4149 section does not contain data (i.e., section only occupies space)
4150 @end table
4151
4152 If no flags are specified, the default flags depend upon the section name.  If
4153 the section name is not recognized, the default will be for the section to have
4154 none of the above flags: it will not be allocated in memory, nor writable, nor
4155 executable.  The section will contain data.
4156
4157 For ELF targets, the assembler supports another type of @code{.section}
4158 directive for compatibility with the Solaris assembler:
4159 @smallexample
4160 .section "@var{name}"[, @var{flags}...]
4161 @end smallexample
4162 Note that the section name is quoted.  There may be a sequence of comma
4163 separated flags:
4164 @table @code
4165 @item #alloc
4166 section is allocatable
4167 @item #write
4168 section is writable
4169 @item #execinstr
4170 section is executable
4171 @end table
4172 @end ifset
4173
4174 @node Set
4175 @section @code{.set @var{symbol}, @var{expression}}
4176
4177 @cindex @code{set} directive
4178 @cindex symbol value, setting
4179 Set the value of @var{symbol} to @var{expression}.  This
4180 changes @var{symbol}'s value and type to conform to
4181 @var{expression}.  If @var{symbol} was flagged as external, it remains
4182 flagged (@pxref{Symbol Attributes}).
4183
4184 You may @code{.set} a symbol many times in the same assembly.
4185
4186 If you @code{.set} a global symbol, the value stored in the object
4187 file is the last value stored into it.
4188
4189 @ifset HPPA
4190 The syntax for @code{set} on the HPPA is
4191 @samp{@var{symbol} .set @var{expression}}.
4192 @end ifset
4193
4194 @node Short
4195 @section @code{.short @var{expressions}}
4196
4197 @cindex @code{short} directive
4198 @ifset GENERIC
4199 @code{.short} is normally the same as @samp{.word}.
4200 @xref{Word,,@code{.word}}.
4201
4202 In some configurations, however, @code{.short} and @code{.word} generate
4203 numbers of different lengths; @pxref{Machine Dependencies}.
4204 @end ifset
4205 @ifclear GENERIC
4206 @ifset W16
4207 @code{.short} is the same as @samp{.word}.  @xref{Word,,@code{.word}}.
4208 @end ifset
4209 @ifset W32
4210 This expects zero or more @var{expressions}, and emits
4211 a 16 bit number for each.
4212 @end ifset
4213 @end ifclear
4214
4215 @node Single
4216 @section @code{.single @var{flonums}}
4217
4218 @cindex @code{single} directive
4219 @cindex floating point numbers (single)
4220 This directive assembles zero or more flonums, separated by commas.  It
4221 has the same effect as @code{.float}.
4222 @ifset GENERIC
4223 The exact kind of floating point numbers emitted depends on how
4224 @code{@value{AS}} is configured.  @xref{Machine Dependencies}.
4225 @end ifset
4226 @ifclear GENERIC
4227 @ifset IEEEFLOAT
4228 On the @value{TARGET} family, @code{.single} emits 32-bit floating point
4229 numbers in @sc{ieee} format.
4230 @end ifset
4231 @end ifclear
4232
4233 @ifset COFF
4234 @node Size
4235 @section @code{.size}
4236
4237 @cindex @code{size} directive
4238 This directive is generated by compilers to include auxiliary debugging
4239 information in the symbol table.  It is only permitted inside
4240 @code{.def}/@code{.endef} pairs.
4241 @ifset BOUT
4242
4243 @samp{.size} is only meaningful when generating COFF format output; when
4244 @code{@value{AS}} is generating @code{b.out}, it accepts this directive but
4245 ignores it.
4246 @end ifset
4247 @end ifset
4248
4249 @ifclear no-space-dir
4250 @node Skip
4251 @section @code{.skip @var{size} , @var{fill}}
4252
4253 @cindex @code{skip} directive
4254 @cindex filling memory
4255 This directive emits @var{size} bytes, each of value @var{fill}.  Both
4256 @var{size} and @var{fill} are absolute expressions.  If the comma and
4257 @var{fill} are omitted, @var{fill} is assumed to be zero.  This is the same as
4258 @samp{.space}.
4259
4260 @node Space
4261 @section @code{.space @var{size} , @var{fill}}
4262
4263 @cindex @code{space} directive
4264 @cindex filling memory
4265 This directive emits @var{size} bytes, each of value @var{fill}.  Both
4266 @var{size} and @var{fill} are absolute expressions.  If the comma
4267 and @var{fill} are omitted, @var{fill} is assumed to be zero.  This is the same
4268 as @samp{.skip}.
4269
4270 @ifset HPPA
4271 @quotation
4272 @emph{Warning:} @code{.space} has a completely different meaning for HPPA
4273 targets; use @code{.block} as a substitute.  See @cite{HP9000 Series 800
4274 Assembly Language Reference Manual} (HP 92432-90001) for the meaning of the
4275 @code{.space} directive.  @xref{HPPA Directives,,HPPA Assembler Directives},
4276 for a summary.
4277 @end quotation
4278 @end ifset
4279 @end ifclear
4280
4281 @ifset A29K
4282 @ifclear GENERIC
4283 @node Space
4284 @section @code{.space}
4285 @cindex @code{space} directive
4286 @end ifclear
4287 On the AMD 29K, this directive is ignored; it is accepted for
4288 compatibility with other AMD 29K assemblers.
4289
4290 @quotation
4291 @emph{Warning:} In most versions of the @sc{gnu} assembler, the directive
4292 @code{.space} has the effect of @code{.block}  @xref{Machine Dependencies}.
4293 @end quotation
4294 @end ifset
4295
4296 @ifset have-stabs
4297 @node Stab
4298 @section @code{.stabd, .stabn, .stabs}
4299
4300 @cindex symbolic debuggers, information for
4301 @cindex @code{stab@var{x}} directives
4302 There are three directives that begin @samp{.stab}.
4303 All emit symbols (@pxref{Symbols}), for use by symbolic debuggers.
4304 The symbols are not entered in the @code{@value{AS}} hash table: they
4305 cannot be referenced elsewhere in the source file.
4306 Up to five fields are required:
4307
4308 @table @var
4309 @item string
4310 This is the symbol's name.  It may contain any character except
4311 @samp{\000}, so is more general than ordinary symbol names.  Some
4312 debuggers used to code arbitrarily complex structures into symbol names
4313 using this field.
4314
4315 @item type
4316 An absolute expression.  The symbol's type is set to the low 8 bits of
4317 this expression.  Any bit pattern is permitted, but @code{@value{LD}}
4318 and debuggers choke on silly bit patterns.
4319
4320 @item other
4321 An absolute expression.  The symbol's ``other'' attribute is set to the
4322 low 8 bits of this expression.
4323
4324 @item desc
4325 An absolute expression.  The symbol's descriptor is set to the low 16
4326 bits of this expression.
4327
4328 @item value
4329 An absolute expression which becomes the symbol's value.
4330 @end table
4331
4332 If a warning is detected while reading a @code{.stabd}, @code{.stabn},
4333 or @code{.stabs} statement, the symbol has probably already been created;
4334 you get a half-formed symbol in your object file.  This is
4335 compatible with earlier assemblers!
4336
4337 @table @code
4338 @cindex @code{stabd} directive
4339 @item .stabd @var{type} , @var{other} , @var{desc}
4340
4341 The ``name'' of the symbol generated is not even an empty string.
4342 It is a null pointer, for compatibility.  Older assemblers used a
4343 null pointer so they didn't waste space in object files with empty
4344 strings.
4345
4346 The symbol's value is set to the location counter,
4347 relocatably.  When your program is linked, the value of this symbol
4348 is the address of the location counter when the @code{.stabd} was
4349 assembled.
4350
4351 @cindex @code{stabn} directive
4352 @item .stabn @var{type} , @var{other} , @var{desc} , @var{value}
4353 The name of the symbol is set to the empty string @code{""}.
4354
4355 @cindex @code{stabs} directive
4356 @item .stabs @var{string} ,  @var{type} , @var{other} , @var{desc} , @var{value}
4357 All five fields are specified.
4358 @end table
4359 @end ifset
4360 @c end     have-stabs
4361
4362 @node String
4363 @section @code{.string} "@var{str}"
4364
4365 @cindex string, copying to object file
4366 @cindex @code{string} directive
4367
4368 Copy the characters in @var{str} to the object file.  You may specify more than
4369 one string to copy, separated by commas.  Unless otherwise specified for a
4370 particular machine, the assembler marks the end of each string with a 0 byte.
4371 You can use any of the escape sequences described in @ref{Strings,,Strings}.
4372
4373 @ifset ELF
4374 @node Symver
4375 @section @code{.symver}
4376 @cindex @code{symver} directive
4377 @cindex symbol versioning
4378 @cindex versions of symbols
4379 Use the @code{.symver} directive to bind symbols to specific version nodes
4380 within a source file.  This is only supported on ELF platforms, and is
4381 typically used when assembling files to be linked into a shared library.
4382 There are cases where it may make sense to use this in objects to be bound
4383 into an application itself so as to override a versioned symbol from a
4384 shared library.
4385
4386 For ELF targets, the @code{.symver} directive is used like this:
4387 @smallexample
4388 .symver @var{name}, @var{name2@@nodename}
4389 @end smallexample
4390 In this case, the symbol @var{name} must exist and be defined within the file
4391 being assembled.  The @code{.versym} directive effectively creates a symbol
4392 alias with the name @var{name2@@nodename}, and in fact the main reason that we
4393 just don't try and create a regular alias is that the @var{@@} character isn't
4394 permitted in symbol names.  The @var{name2} part of the name is the actual name
4395 of the symbol by which it will be externally referenced.  The name @var{name}
4396 itself is merely a name of convenience that is used so that it is possible to
4397 have definitions for multiple versions of a function within a single source
4398 file, and so that the compiler can unambiguously know which version of a
4399 function is being mentioned.  The @var{nodename} portion of the alias should be
4400 the name of a node specified in the version script supplied to the linker when
4401 building a shared library.  If you are attempting to override a versioned
4402 symbol from a shared library, then @var{nodename} should correspond to the
4403 nodename of the symbol you are trying to override.
4404 @end ifset
4405
4406 @ifset COFF
4407 @node Tag
4408 @section @code{.tag @var{structname}}
4409
4410 @cindex COFF structure debugging
4411 @cindex structure debugging, COFF
4412 @cindex @code{tag} directive
4413 This directive is generated by compilers to include auxiliary debugging
4414 information in the symbol table.  It is only permitted inside
4415 @code{.def}/@code{.endef} pairs.  Tags are used to link structure
4416 definitions in the symbol table with instances of those structures.
4417 @ifset BOUT
4418
4419 @samp{.tag} is only used when generating COFF format output; when
4420 @code{@value{AS}} is generating @code{b.out}, it accepts this directive but
4421 ignores it.
4422 @end ifset
4423 @end ifset
4424
4425 @node Text
4426 @section @code{.text @var{subsection}}
4427
4428 @cindex @code{text} directive
4429 Tells @code{@value{AS}} to assemble the following statements onto the end of
4430 the text subsection numbered @var{subsection}, which is an absolute
4431 expression.  If @var{subsection} is omitted, subsection number zero
4432 is used.
4433
4434 @node Title
4435 @section @code{.title "@var{heading}"}
4436
4437 @cindex @code{title} directive
4438 @cindex listing control: title line
4439 Use @var{heading} as the title (second line, immediately after the
4440 source file name and pagenumber) when generating assembly listings.
4441
4442 This directive affects subsequent pages, as well as the current page if
4443 it appears within ten lines of the top of a page.
4444
4445 @ifset COFF
4446 @node Type
4447 @section @code{.type @var{int}}
4448
4449 @cindex COFF symbol type
4450 @cindex symbol type, COFF
4451 @cindex @code{type} directive
4452 This directive, permitted only within @code{.def}/@code{.endef} pairs,
4453 records the integer @var{int} as the type attribute of a symbol table entry.
4454 @ifset BOUT
4455
4456 @samp{.type} is associated only with COFF format output; when
4457 @code{@value{AS}} is configured for @code{b.out} output, it accepts this
4458 directive but ignores it.
4459 @end ifset
4460 @end ifset
4461
4462 @ifset COFF
4463 @node Val
4464 @section @code{.val @var{addr}}
4465
4466 @cindex @code{val} directive
4467 @cindex COFF value attribute
4468 @cindex value attribute, COFF
4469 This directive, permitted only within @code{.def}/@code{.endef} pairs,
4470 records the address @var{addr} as the value attribute of a symbol table
4471 entry.
4472 @ifset BOUT
4473
4474 @samp{.val} is used only for COFF output; when @code{@value{AS}} is
4475 configured for @code{b.out}, it accepts this directive but ignores it.
4476 @end ifset
4477 @end ifset
4478
4479 @node Word
4480 @section @code{.word @var{expressions}}
4481
4482 @cindex @code{word} directive
4483 This directive expects zero or more @var{expressions}, of any section,
4484 separated by commas.
4485 @ifclear GENERIC
4486 @ifset W32
4487 For each expression, @code{@value{AS}} emits a 32-bit number.
4488 @end ifset
4489 @ifset W16
4490 For each expression, @code{@value{AS}} emits a 16-bit number.
4491 @end ifset
4492 @end ifclear
4493 @ifset GENERIC
4494
4495 The size of the number emitted, and its byte order,
4496 depend on what target computer the assembly is for.
4497 @end ifset
4498
4499 @c on amd29k, i960, sparc the "special treatment to support compilers" doesn't
4500 @c happen---32-bit addressability, period; no long/short jumps.
4501 @ifset DIFF-TBL-KLUGE
4502 @cindex difference tables altered
4503 @cindex altered difference tables
4504 @quotation
4505 @emph{Warning: Special Treatment to support Compilers}
4506 @end quotation
4507
4508 @ifset GENERIC
4509 Machines with a 32-bit address space, but that do less than 32-bit
4510 addressing, require the following special treatment.  If the machine of
4511 interest to you does 32-bit addressing (or doesn't require it;
4512 @pxref{Machine Dependencies}), you can ignore this issue.
4513
4514 @end ifset
4515 In order to assemble compiler output into something that works,
4516 @code{@value{AS}} occasionlly does strange things to @samp{.word} directives.
4517 Directives of the form @samp{.word sym1-sym2} are often emitted by
4518 compilers as part of jump tables.  Therefore, when @code{@value{AS}} assembles a
4519 directive of the form @samp{.word sym1-sym2}, and the difference between
4520 @code{sym1} and @code{sym2} does not fit in 16 bits, @code{@value{AS}}
4521 creates a @dfn{secondary jump table}, immediately before the next label.
4522 This secondary jump table is preceded by a short-jump to the
4523 first byte after the secondary table.  This short-jump prevents the flow
4524 of control from accidentally falling into the new table.  Inside the
4525 table is a long-jump to @code{sym2}.  The original @samp{.word}
4526 contains @code{sym1} minus the address of the long-jump to
4527 @code{sym2}.
4528
4529 If there were several occurrences of @samp{.word sym1-sym2} before the
4530 secondary jump table, all of them are adjusted.  If there was a
4531 @samp{.word sym3-sym4}, that also did not fit in sixteen bits, a
4532 long-jump to @code{sym4} is included in the secondary jump table,
4533 and the @code{.word} directives are adjusted to contain @code{sym3}
4534 minus the address of the long-jump to @code{sym4}; and so on, for as many
4535 entries in the original jump table as necessary.
4536
4537 @ifset INTERNALS
4538 @emph{This feature may be disabled by compiling @code{@value{AS}} with the
4539 @samp{-DWORKING_DOT_WORD} option.} This feature is likely to confuse
4540 assembly language programmers.
4541 @end ifset
4542 @end ifset
4543 @c end     DIFF-TBL-KLUGE
4544
4545 @node Deprecated
4546 @section Deprecated Directives
4547
4548 @cindex deprecated directives
4549 @cindex obsolescent directives
4550 One day these directives won't work.
4551 They are included for compatibility with older assemblers.
4552 @table @t
4553 @item .abort
4554 @item .app-file
4555 @item .line
4556 @end table
4557
4558 @ifset GENERIC
4559 @node Machine Dependencies
4560 @chapter Machine Dependent Features
4561
4562 @cindex machine dependencies
4563 The machine instruction sets are (almost by definition) different on
4564 each machine where @code{@value{AS}} runs.  Floating point representations
4565 vary as well, and @code{@value{AS}} often supports a few additional
4566 directives or command-line options for compatibility with other
4567 assemblers on a particular platform.  Finally, some versions of
4568 @code{@value{AS}} support special pseudo-instructions for branch
4569 optimization.
4570
4571 This chapter discusses most of these differences, though it does not
4572 include details on any machine's instruction set.  For details on that
4573 subject, see the hardware manufacturer's manual.
4574
4575 @menu
4576 @ifset A29K
4577 * AMD29K-Dependent::            AMD 29K Dependent Features
4578 @end ifset
4579 @c start-sanitize-arc
4580 @ifset ARC
4581 * ARC-Dependent::               ARC Dependent Features
4582 @end ifset
4583 @c end-sanitize-arc
4584 @ifset D10V
4585 * D10V-Dependent::              D10V Dependent Features
4586 @end ifset
4587 @ifset H8/300
4588 * H8/300-Dependent::            Hitachi H8/300 Dependent Features
4589 @end ifset
4590 @ifset H8/500
4591 * H8/500-Dependent::            Hitachi H8/500 Dependent Features
4592 @end ifset
4593 @ifset HPPA
4594 * HPPA-Dependent::              HPPA Dependent Features
4595 @end ifset
4596 @ifset I80386
4597 * i386-Dependent::              Intel 80386 Dependent Features
4598 @end ifset
4599 @ifset I960
4600 * i960-Dependent::              Intel 80960 Dependent Features
4601 @end ifset
4602 @ifset M680X0
4603 * M68K-Dependent::              M680x0 Dependent Features
4604 @end ifset
4605 @ifset MIPS
4606 * MIPS-Dependent::              MIPS Dependent Features
4607 @end ifset
4608 @ifset SH
4609 * SH-Dependent::                Hitachi SH Dependent Features
4610 @end ifset
4611 @ifset SPARC
4612 * Sparc-Dependent::             SPARC Dependent Features
4613 @end ifset
4614 @ifset Z8000
4615 * Z8000-Dependent::             Z8000 Dependent Features
4616 @end ifset
4617 @ifset VAX
4618 * Vax-Dependent::               VAX Dependent Features
4619 @end ifset
4620 @end menu
4621
4622 @lowersections
4623 @end ifset
4624
4625 @c The following major nodes are *sections* in the GENERIC version, *chapters*
4626 @c in single-cpu versions.  This is mainly achieved by @lowersections.  There is a
4627 @c peculiarity: to preserve cross-references, there must be a node called
4628 @c "Machine Dependencies".  Hence the conditional nodenames in each
4629 @c major node below.  Node defaulting in makeinfo requires adjacency of
4630 @c node and sectioning commands; hence the repetition of @chapter BLAH
4631 @c in both conditional blocks.
4632
4633 @c start-sanitize-arc
4634 @ifset ARC
4635 @ifset GENERIC
4636 @page
4637 @node ARC-Dependent
4638 @chapter ARC Dependent Features
4639 @end ifset
4640 @ifclear GENERIC
4641 @node Machine Dependencies
4642 @chapter ARC Dependent Features
4643 @end ifclear
4644
4645 @cindex ARC support
4646 @menu
4647 * ARC-Opts::                    Options
4648 * ARC-Float::                   Floating Point
4649 * ARC-Directives::              Sparc Machine Directives
4650 @end menu
4651
4652 @node ARC-Opts
4653 @section Options
4654
4655 @cindex options for ARC
4656 @cindex ARC options
4657 @cindex architectures, ARC
4658 @cindex ARC architectures
4659 The ARC chip family includes several successive levels (or other
4660 variants) of chip, using the same core instruction set, but including
4661 a few additional instructions at each level.
4662
4663 By default, @code{@value{AS}} assumes the core instruction set (ARC
4664 base).  The @code{.cpu} pseudo-op is used to select a different variant.
4665
4666 @table @code
4667 @cindex @code{-mbig-endian} option (ARC)
4668 @cindex @code{-mlittle-endian} option (ARC)
4669 @cindex ARC big-endian output
4670 @cindex ARC little-endian output
4671 @cindex big-endian output, ARC
4672 @cindex little-endian output, ARC
4673 @item -mbig-endian
4674 @itemx -mlittle-endian
4675 Any @sc{arc} configuration of @code{@value{AS}} can select big-endian or
4676 little-endian output at run time (unlike most other @sc{gnu} development
4677 tools, which must be configured for one or the other).  Use
4678 @samp{-mbig-endian} to select big-endian output, and @samp{-mlittle-endian}
4679 for little-endian.
4680 @end table
4681
4682 @node ARC-Float
4683 @section Floating Point
4684
4685 @cindex floating point, ARC (@sc{ieee})
4686 @cindex ARC floating point (@sc{ieee})
4687 The ARC cpu family currently does not have hardware floating point
4688 support.  Software floating point support is provided by @code{GCC}
4689 and uses @sc{ieee} floating-point numbers.
4690
4691 @node ARC-Directives
4692 @section ARC Machine Directives
4693
4694 @cindex ARC machine directives
4695 @cindex machine directives, ARC
4696 The ARC version of @code{@value{AS}} supports the following additional
4697 machine directives:
4698
4699 @table @code
4700 @item .cpu
4701 @cindex @code{cpu} directive, SPARC
4702 This must be followed by the desired cpu.  It must be one of
4703 @code{base}, @code{host}, @code{graphics}, or @code{audio}.
4704
4705 @end table
4706
4707 @end ifset
4708 @c end-sanitize-arc
4709
4710 @ifset A29K
4711 @include c-a29k.texi
4712 @end ifset
4713
4714 @ifset Hitachi-all
4715 @ifclear GENERIC
4716 @node Machine Dependencies
4717 @chapter Machine Dependent Features
4718
4719 The machine instruction sets are different on each Hitachi chip family,
4720 and there are also some syntax differences among the families.  This
4721 chapter describes the specific @code{@value{AS}} features for each
4722 family.
4723
4724 @menu
4725 * H8/300-Dependent::            Hitachi H8/300 Dependent Features
4726 * H8/500-Dependent::            Hitachi H8/500 Dependent Features
4727 * SH-Dependent::                Hitachi SH Dependent Features
4728 @end menu
4729 @lowersections
4730 @end ifclear
4731 @end ifset
4732
4733 @ifset D10V
4734 @include c-d10v.texi
4735 @end ifset
4736
4737 @ifset H8/300
4738 @include c-h8300.texi
4739 @end ifset
4740
4741 @ifset H8/500
4742 @include c-h8500.texi
4743 @end ifset
4744
4745 @ifset HPPA
4746 @include c-hppa.texi
4747 @end ifset
4748
4749 @ifset I80386
4750 @include c-i386.texi
4751 @end ifset
4752
4753 @ifset I960
4754 @include c-i960.texi
4755 @end ifset
4756
4757 @ifset M680X0
4758 @include c-m68k.texi
4759 @end ifset
4760
4761 @ifset MIPS
4762 @include c-mips.texi
4763 @end ifset
4764
4765 @ifset NS32K
4766 @include c-ns32k.texi
4767 @end ifset
4768
4769 @ifset SH
4770 @include c-sh.texi
4771 @end ifset
4772
4773 @ifset SPARC
4774 @include c-sparc.texi
4775 @end ifset
4776
4777 @ifset Z8000
4778 @include c-z8k.texi
4779 @end ifset
4780
4781 @ifset VAX
4782 @include c-vax.texi
4783 @end ifset
4784
4785 @ifset GENERIC
4786 @c reverse effect of @down at top of generic Machine-Dep chapter
4787 @raisesections
4788 @end ifset
4789
4790 @node Reporting Bugs
4791 @chapter Reporting Bugs
4792 @cindex bugs in @code{@value{AS}}
4793 @cindex reporting bugs in @code{@value{AS}}
4794
4795 Your bug reports play an essential role in making @code{@value{AS}} reliable.
4796
4797 Reporting a bug may help you by bringing a solution to your problem, or it may
4798 not.  But in any case the principal function of a bug report is to help the
4799 entire community by making the next version of @code{@value{AS}} work better.
4800 Bug reports are your contribution to the maintenance of @code{@value{AS}}.
4801
4802 In order for a bug report to serve its purpose, you must include the
4803 information that enables us to fix the bug.
4804
4805 @menu
4806 * Bug Criteria::                Have you found a bug?
4807 * Bug Reporting::               How to report bugs
4808 @end menu
4809
4810 @node Bug Criteria
4811 @section Have you found a bug?
4812 @cindex bug criteria
4813
4814 If you are not sure whether you have found a bug, here are some guidelines:
4815
4816 @itemize @bullet
4817 @cindex fatal signal
4818 @cindex assembler crash
4819 @cindex crash of assembler
4820 @item
4821 If the assembler gets a fatal signal, for any input whatever, that is a
4822 @code{@value{AS}} bug.  Reliable assemblers never crash.
4823
4824 @cindex error on valid input
4825 @item
4826 If @code{@value{AS}} produces an error message for valid input, that is a bug.
4827
4828 @cindex invalid input
4829 @item
4830 If @code{@value{AS}} does not produce an error message for invalid input, that
4831 is a bug.  However, you should note that your idea of ``invalid input'' might
4832 be our idea of ``an extension'' or ``support for traditional practice''.
4833
4834 @item
4835 If you are an experienced user of assemblers, your suggestions for improvement
4836 of @code{@value{AS}} are welcome in any case.
4837 @end itemize
4838
4839 @node Bug Reporting
4840 @section How to report bugs
4841 @cindex bug reports
4842 @cindex @code{@value{AS}} bugs, reporting
4843
4844 A number of companies and individuals offer support for @sc{gnu} products.  If
4845 you obtained @code{@value{AS}} from a support organization, we recommend you
4846 contact that organization first.
4847
4848 You can find contact information for many support companies and
4849 individuals in the file @file{etc/SERVICE} in the @sc{gnu} Emacs
4850 distribution.
4851
4852 In any event, we also recommend that you send bug reports for @code{@value{AS}}
4853 to @samp{bug-gnu-utils@@prep.ai.mit.edu}.
4854
4855 The fundamental principle of reporting bugs usefully is this:
4856 @strong{report all the facts}.  If you are not sure whether to state a
4857 fact or leave it out, state it!
4858
4859 Often people omit facts because they think they know what causes the problem
4860 and assume that some details do not matter.  Thus, you might assume that the
4861 name of a symbol you use in an example does not matter.  Well, probably it does
4862 not, but one cannot be sure.  Perhaps the bug is a stray memory reference which
4863 happens to fetch from the location where that name is stored in memory;
4864 perhaps, if the name were different, the contents of that location would fool
4865 the assembler into doing the right thing despite the bug.  Play it safe and
4866 give a specific, complete example.  That is the easiest thing for you to do,
4867 and the most helpful.
4868
4869 Keep in mind that the purpose of a bug report is to enable us to fix the bug if
4870 it is new to us.  Therefore, always write your bug reports on the assumption
4871 that the bug has not been reported previously.
4872
4873 Sometimes people give a few sketchy facts and ask, ``Does this ring a
4874 bell?''  Those bug reports are useless, and we urge everyone to
4875 @emph{refuse to respond to them} except to chide the sender to report
4876 bugs properly.
4877
4878 To enable us to fix the bug, you should include all these things:
4879
4880 @itemize @bullet
4881 @item
4882 The version of @code{@value{AS}}.  @code{@value{AS}} announces it if you start
4883 it with the @samp{--version} argument.
4884
4885 Without this, we will not know whether there is any point in looking for
4886 the bug in the current version of @code{@value{AS}}.
4887
4888 @item
4889 Any patches you may have applied to the @code{@value{AS}} source.
4890
4891 @item
4892 The type of machine you are using, and the operating system name and
4893 version number.
4894
4895 @item
4896 What compiler (and its version) was used to compile @code{@value{AS}}---e.g.
4897 ``@code{gcc-2.7}''.
4898
4899 @item
4900 The command arguments you gave the assembler to assemble your example and
4901 observe the bug.  To guarantee you will not omit something important, list them
4902 all.  A copy of the Makefile (or the output from make) is sufficient.
4903
4904 If we were to try to guess the arguments, we would probably guess wrong
4905 and then we might not encounter the bug.
4906
4907 @item
4908 A complete input file that will reproduce the bug.  If the bug is observed when
4909 the assembler is invoked via a compiler, send the assembler source, not the
4910 high level language source.  Most compilers will produce the assembler source
4911 when run with the @samp{-S} option.  If you are using @code{@value{GCC}}, use
4912 the options @samp{-v --save-temps}; this will save the assembler source in a
4913 file with an extension of @file{.s}, and also show you exactly how
4914 @code{@value{AS}} is being run.
4915
4916 @item
4917 A description of what behavior you observe that you believe is
4918 incorrect.  For example, ``It gets a fatal signal.''
4919
4920 Of course, if the bug is that @code{@value{AS}} gets a fatal signal, then we
4921 will certainly notice it.  But if the bug is incorrect output, we might not
4922 notice unless it is glaringly wrong.  You might as well not give us a chance to
4923 make a mistake.
4924
4925 Even if the problem you experience is a fatal signal, you should still say so
4926 explicitly.  Suppose something strange is going on, such as, your copy of
4927 @code{@value{AS}} is out of synch, or you have encountered a bug in the C
4928 library on your system.  (This has happened!)  Your copy might crash and ours
4929 would not.  If you told us to expect a crash, then when ours fails to crash, we
4930 would know that the bug was not happening for us.  If you had not told us to
4931 expect a crash, then we would not be able to draw any conclusion from our
4932 observations.
4933
4934 @item
4935 If you wish to suggest changes to the @code{@value{AS}} source, send us context
4936 diffs, as generated by @code{diff} with the @samp{-u}, @samp{-c}, or @samp{-p}
4937 option.  Always send diffs from the old file to the new file.  If you even
4938 discuss something in the @code{@value{AS}} source, refer to it by context, not
4939 by line number.
4940
4941 The line numbers in our development sources will not match those in your
4942 sources.  Your line numbers would convey no useful information to us.
4943 @end itemize
4944
4945 Here are some things that are not necessary:
4946
4947 @itemize @bullet
4948 @item
4949 A description of the envelope of the bug.
4950
4951 Often people who encounter a bug spend a lot of time investigating
4952 which changes to the input file will make the bug go away and which
4953 changes will not affect it.
4954
4955 This is often time consuming and not very useful, because the way we
4956 will find the bug is by running a single example under the debugger
4957 with breakpoints, not by pure deduction from a series of examples.
4958 We recommend that you save your time for something else.
4959
4960 Of course, if you can find a simpler example to report @emph{instead}
4961 of the original one, that is a convenience for us.  Errors in the
4962 output will be easier to spot, running under the debugger will take
4963 less time, and so on.
4964
4965 However, simplification is not vital; if you do not want to do this,
4966 report the bug anyway and send us the entire test case you used.
4967
4968 @item
4969 A patch for the bug.
4970
4971 A patch for the bug does help us if it is a good one.  But do not omit
4972 the necessary information, such as the test case, on the assumption that
4973 a patch is all we need.  We might see problems with your patch and decide
4974 to fix the problem another way, or we might not understand it at all.
4975
4976 Sometimes with a program as complicated as @code{@value{AS}} it is very hard to
4977 construct an example that will make the program follow a certain path through
4978 the code.  If you do not send us the example, we will not be able to construct
4979 one, so we will not be able to verify that the bug is fixed.
4980
4981 And if we cannot understand what bug you are trying to fix, or why your
4982 patch should be an improvement, we will not install it.  A test case will
4983 help us to understand.
4984
4985 @item
4986 A guess about what the bug is or what it depends on.
4987
4988 Such guesses are usually wrong.  Even we cannot guess right about such
4989 things without first using the debugger to find the facts.
4990 @end itemize
4991
4992 @node Acknowledgements
4993 @chapter Acknowledgements
4994
4995 If you have contributed to @code{@value{AS}} and your name isn't listed here,
4996 it is not meant as a slight.  We just don't know about it.  Send mail to the
4997 maintainer, and we'll correct the situation.  Currently 
4998 @c (January 1994), 
4999 the maintainer is Ken Raeburn (email address @code{raeburn@@cygnus.com}).
5000
5001 Dean Elsner wrote the original @sc{gnu} assembler for the VAX.@footnote{Any
5002 more details?}
5003
5004 Jay Fenlason maintained GAS for a while, adding support for GDB-specific debug
5005 information and the 68k series machines, most of the preprocessing pass, and
5006 extensive changes in @file{messages.c}, @file{input-file.c}, @file{write.c}.
5007
5008 K. Richard Pixley maintained GAS for a while, adding various enhancements and
5009 many bug fixes, including merging support for several processors, breaking GAS
5010 up to handle multiple object file format back ends (including heavy rewrite,
5011 testing, an integration of the coff and b.out back ends), adding configuration
5012 including heavy testing and verification of cross assemblers and file splits
5013 and renaming, converted GAS to strictly ANSI C including full prototypes, added
5014 support for m680[34]0 and cpu32, did considerable work on i960 including a COFF
5015 port (including considerable amounts of reverse engineering), a SPARC opcode
5016 file rewrite, DECstation, rs6000, and hp300hpux host ports, updated ``know''
5017 assertions and made them work, much other reorganization, cleanup, and lint.
5018
5019 Ken Raeburn wrote the high-level BFD interface code to replace most of the code
5020 in format-specific I/O modules.
5021
5022 The original VMS support was contributed by David L. Kashtan.  Eric Youngdale
5023 has done much work with it since.
5024
5025 The Intel 80386 machine description was written by Eliot Dresselhaus.
5026
5027 Minh Tran-Le at IntelliCorp contributed some AIX 386 support.
5028
5029 The Motorola 88k machine description was contributed by Devon Bowen of Buffalo
5030 University and Torbjorn Granlund of the Swedish Institute of Computer Science.
5031
5032 Keith Knowles at the Open Software Foundation wrote the original MIPS back end
5033 (@file{tc-mips.c}, @file{tc-mips.h}), and contributed Rose format support
5034 (which hasn't been merged in yet).  Ralph Campbell worked with the MIPS code to
5035 support a.out format.
5036
5037 Support for the Zilog Z8k and Hitachi H8/300 and H8/500 processors (tc-z8k,
5038 tc-h8300, tc-h8500), and IEEE 695 object file format (obj-ieee), was written by
5039 Steve Chamberlain of Cygnus Support.  Steve also modified the COFF back end to
5040 use BFD for some low-level operations, for use with the H8/300 and AMD 29k
5041 targets.
5042
5043 John Gilmore built the AMD 29000 support, added @code{.include} support, and
5044 simplified the configuration of which versions accept which directives.  He
5045 updated the 68k machine description so that Motorola's opcodes always produced
5046 fixed-size instructions (e.g. @code{jsr}), while synthetic instructions
5047 remained shrinkable (@code{jbsr}).  John fixed many bugs, including true tested
5048 cross-compilation support, and one bug in relaxation that took a week and
5049 required the proverbial one-bit fix.
5050
5051 Ian Lance Taylor of Cygnus Support merged the Motorola and MIT syntax for the
5052 68k, completed support for some COFF targets (68k, i386 SVR3, and SCO Unix),
5053 added support for MIPS ECOFF and ELF targets, wrote the initial RS/6000 and
5054 PowerPC assembler, and made a few other minor patches.
5055
5056 Steve Chamberlain made @code{@value{AS}} able to generate listings.
5057
5058 Hewlett-Packard contributed support for the HP9000/300.
5059
5060 Jeff Law wrote GAS and BFD support for the native HPPA object format (SOM)
5061 along with a fairly extensive HPPA testsuite (for both SOM and ELF object
5062 formats).  This work was supported by both the Center for Software Science at
5063 the University of Utah and Cygnus Support.
5064
5065 Support for ELF format files has been worked on by Mark Eichin of Cygnus
5066 Support (original, incomplete implementation for SPARC), Pete Hoogenboom and
5067 Jeff Law at the University of Utah (HPPA mainly), Michael Meissner of the Open
5068 Software Foundation (i386 mainly), and Ken Raeburn of Cygnus Support (sparc,
5069 and some initial 64-bit support).
5070
5071 Richard Henderson rewrote the Alpha assembler. Klaus Kaempf wrote GAS and BFD
5072 support for openVMS/Alpha.
5073
5074 Several engineers at Cygnus Support have also provided many small bug fixes and
5075 configuration enhancements.
5076
5077 Many others have contributed large or small bugfixes and enhancements.  If
5078 you have contributed significant work and are not mentioned on this list, and
5079 want to be, let us know.  Some of the history has been lost; we are not
5080 intentionally leaving anyone out.
5081
5082 @node Index
5083 @unnumbered Index
5084
5085 @printindex cp
5086
5087 @contents
5088 @bye
5089 @c Local Variables:
5090 @c fill-column: 79
5091 @c End: