6 .Nd Using as (machine specific)
8 This file is a user guide to the GNU assembler
10 version "2.17.50 [FreeBSD] 2007-07-03". This version of the file describes
12 configured to generate code for machine specific architectures.
14 This document is distributed under the terms of the GNU Free Documentation
15 License. A copy of the license is included in the section entitled \(lqGNU Free
16 Documentation License\(rq.
19 Here is a brief summary of how to invoke
21 For details, see Invoking,,Command-Line Options.
23 .Bd -literal -offset indent
24 as [-a[cdhlns][=file]] [--alternate] [-D]
25 [--defsym sym=val] [-f] [-g] [--gstabs]
26 [--gstabs+] [--gdwarf-2] [--help] [-I dir] [-J]
27 [-K] [-L] [--listing-lhs-width=NUM]
28 [--listing-lhs-width2=NUM] [--listing-rhs-width=NUM]
29 [--listing-cont-lines=NUM] [--keep-locals] [-o
30 objfile] [-R] [--reduce-memory-overheads] [--statistics]
31 [-v] [-version] [--version] [-W] [--warn]
32 [--fatal-warnings] [-w] [-x] [-Z] [@FILE]
33 [--target-help] [target-options]
37 [-mcpu=processor[+extension...]]
38 [-march=architecture[+extension...]]
39 [-mfpu=floating-point-format]
44 [-mapcs-32|-mapcs-26|-mapcs-float|
46 [-mthumb-interwork] [-k]
51 [-march=CPU] [-mtune=CPU]
55 [-mconstant-gp|-mauto-pic]
56 [-milp32|-milp64|-mlp64|-mp64]
58 [-mtune=itanium1|-mtune=itanium2]
59 [-munwind-check=warning|-munwind-check=error]
60 [-mhint.b=ok|-mhint.b=warning|-mhint.b=error]
61 [-x|-xexplicit] [-xauto] [-xdebug]
65 [-nocpp] [-EL] [-EB] [-O[optimization level]]
66 [-g[debug level]] [-G num] [-KPIC] [-call_shared]
67 [-non_shared] [-xgot [-mvxworks-pic]
68 [-mabi=ABI] [-32] [-n32] [-64] [-mfp32] [-mgp32]
69 [-march=CPU] [-mtune=CPU] [-mips1] [-mips2]
70 [-mips3] [-mips4] [-mips5] [-mips32] [-mips32r2]
72 [-construct-floats] [-no-construct-floats]
73 [-trap] [-no-break] [-break] [-no-trap]
74 [-mfix7000] [-mno-fix7000]
75 [-mips16] [-no-mips16]
76 [-msmartmips] [-mno-smartmips]
77 [-mips3d] [-no-mips3d]
80 [-mdspr2] [-mno-dspr2]
82 [-mdebug] [-no-mdebug]
86 Target PowerPC options:
87 [-mpwrx|-mpwr2|-mpwr|-m601|-mppc|-mppc32|-m603|-m604|
88 -m403|-m405|-mppc64|-m620|-mppc64bridge|-mbooke|
90 [-mcom|-many|-maltivec] [-memb]
91 [-mregnames|-mno-regnames]
92 [-mrelocatable|-mrelocatable-lib]
93 [-mlittle|-mlittle-endian|-mbig|-mbig-endian]
94 [-msolaris|-mno-solaris]
98 [-Av6|-Av7|-Av8|-Asparclet|-Asparclite
99 -Av8plus|-Av8plusa|-Av9|-Av9a]
100 [-xarch=v8plus|-xarch=v8plusa] [-bump]
109 Read command-line options from
111 The options read are inserted in place of the original @
115 does not exist, or cannot be read, then the option will be treated literally,
120 are separated by whitespace. A whitespace character may be included in an
121 option by surrounding the entire option in either single or double quotes.
122 Any character (including a backslash) may be included by prefixing the character
123 to be included with a backslash. The
125 may itself contain additional @
127 options; any such options will be processed recursively.
130 Turn on listings, in any of a variety of ways:
134 omit false conditionals
137 omit debugging directives
140 include high-level source
146 include macro expansions
149 omit forms processing
155 set the name of the listing file
158 You may combine these options; for example, use
160 for assembly listing without forms processing. The
162 option, if used, must be the last one. By itself,
168 Begin in alternate macro mode.See Section
172 Ignored. This option is accepted for script compatibility with calls to other
175 .It --defsym Va sym= Va value
180 before assembling the input file.
182 must be an integer constant. As in C, a leading
184 indicates a hexadecimal value, and a leading
186 indicates an octal value. The value of the symbol can be overridden inside
187 a source file via the use of a
192 \(lqfast\(rq---skip whitespace and comment preprocessing (assume source is compiler
197 Generate debugging information for each assembler source line using whichever
198 debug format is preferred by the target. This currently means either STABS,
202 Generate stabs debugging information for each assembler line. This may help
203 debugging assembler code, if the debugger can handle it.
206 Generate stabs debugging information for each assembler line, with GNU extensions
207 that probably only gdb can handle, and that could make other debuggers crash
208 or refuse to read your program. This may help debugging assembler code. Currently
209 the only GNU extension is the location of the current working directory at
213 Generate DWARF2 debugging information for each assembler line. This may help
214 debugging assembler code, if the debugger can handle it. Note---this option
215 is only supported by some targets, not all of them.
218 Print a summary of the command line options and exit.
221 Print a summary of all target specific options and exit.
226 to the search list for
231 Don't warn about signed overflow.
234 This option is accepted but has no effect on the machine specific family.
238 Keep (in the symbol table) local symbols. These symbols start with system-specific
239 local label prefixes, typically
243 for traditional a.out systems.See Section
246 .It --listing-lhs-width= Va number
247 Set the maximum width, in words, of the output data column for an assembler
251 .It --listing-lhs-width2= Va number
252 Set the maximum width, in words, of the output data column for continuation
253 lines in an assembler listing to
256 .It --listing-rhs-width= Va number
257 Set the maximum width of an input source line, as displayed in a listing,
262 .It --listing-cont-lines= Va number
263 Set the maximum number of lines printed in a listing for a single line of
269 Name the object-file output from
274 Fold the data section into the text section.
276 Set the default size of GAS's hash tables to a prime number close to
278 Increasing this value can reduce the length of time it takes the assembler
279 to perform its tasks, at the expense of increasing the assembler's memory
280 requirements. Similarly reducing this value can reduce the memory requirements
281 at the expense of speed.
283 .It --reduce-memory-overheads
284 This option reduces GAS's memory requirements, at the expense of making the
285 assembly processes slower. Currently this switch is a synonym for
286 .Li --hash-size=4051 ,
287 but in the future it may have other effects as well.
290 Print the maximum space (in bytes) and total time (in seconds) used by assembly.
292 .It --strip-local-absolute
293 Remove local absolute symbols from the outgoing symbol table.
308 Suppress warning messages.
311 Treat warnings as errors.
314 Don't suppress warning messages or treat them as errors.
323 Generate an object file even after errors.
325 .It -- | Va files ...
326 Standard input, or source files to assemble.
329 The following options are available when as is configured for the ARM processor
333 .It -mcpu= Va processor[+ Va extension...]
334 Specify which ARM processor variant is the target.
335 .It -march= Va architecture[+ Va extension...]
336 Specify which ARM architecture variant is used by the target.
337 .It -mfpu= Va floating-point-format
338 Select which Floating Point architecture is the target.
339 .It -mfloat-abi= Va abi
340 Select which floating point ABI is in use.
342 Enable Thumb only instruction decoding.
343 .It -mapcs-32 | -mapcs-26 | -mapcs-float | -mapcs-reentrant
344 Select which procedure calling convention is in use.
346 Select either big-endian (-EB) or little-endian (-EL) output.
347 .It -mthumb-interwork
348 Specify that the code has been generated with interworking between Thumb and
351 Specify that PIC code has been generated.
354 The following options are available when
356 is configured for the SPARC architecture:
359 .It -Av6 | -Av7 | -Av8 | -Asparclet | -Asparclite
360 .It -Av8plus | -Av8plusa | -Av9 | -Av9a
361 Explicitly select a variant of the SPARC architecture.
366 select a 32 bit environment.
370 select a 64 bit environment.
375 enable the SPARC V9 instruction set with UltraSPARC extensions.
377 .It -xarch=v8plus | -xarch=v8plusa
378 For compatibility with the Solaris v9 assembler. These options are equivalent
379 to -Av8plus and -Av8plusa, respectively.
382 Warn when the assembler switches to another architecture.
385 The following options are available when as is configured for a mips processor.
389 This option sets the largest size of an object that can be referenced implicitly
392 register. It is only accepted for targets that use ECOFF format, such as a
393 DECstation running Ultrix. The default value is 8.
396 Generate \(lqbig endian\(rq format output.
399 Generate \(lqlittle endian\(rq format output.
410 Generate code for a particular mips Instruction Set Architecture level.
430 correspond to generic
433 .Li MIPS32 Release 2 ,
437 ISA processors, respectively.
440 Generate code for a particular mips cpu.
443 Schedule and tune for a particular mips cpu.
447 Cause nops to be inserted if the read of the destination register of an mfhi
448 or mflo instruction occurs in the following two instructions.
452 Cause stabs-style debugging output to go into an ECOFF-style .mdebug section
453 instead of the standard ELF .stabs sections.
457 Control generation of
463 The register sizes are normally inferred from the ISA and ABI, but these flags
464 force a certain group of registers to be treated as 32 bits wide at all times.
466 controls the size of general-purpose registers and
468 controls the size of floating-point registers.
472 Generate code for the MIPS 16 processor. This is equivalent to putting
474 at the start of the assembly file.
476 turns off this option.
480 Enables the SmartMIPS extension to the MIPS32 instruction set. This is equivalent
483 at the start of the assembly file.
485 turns off this option.
489 Generate code for the MIPS-3D Application Specific Extension. This tells the
490 assembler to accept MIPS-3D instructions.
492 turns off this option.
496 Generate code for the MDMX Application Specific Extension. This tells the
497 assembler to accept MDMX instructions.
499 turns off this option.
503 Generate code for the DSP Release 1 Application Specific Extension. This tells
504 the assembler to accept DSP Release 1 instructions.
506 turns off this option.
510 Generate code for the DSP Release 2 Application Specific Extension. This option
511 implies -mdsp. This tells the assembler to accept DSP Release 2 instructions.
513 turns off this option.
517 Generate code for the MT Application Specific Extension. This tells the assembler
518 to accept MT instructions.
520 turns off this option.
522 .It --construct-floats
523 .It --no-construct-floats
525 .Li --no-construct-floats
526 option disables the construction of double width floating point constants
527 by loading the two halves of the value into the two single width floating
528 point registers that make up the double width register. By default
529 .Li --construct-floats
530 is selected, allowing construction of these floating point constants.
532 .It --emulation= Va name
537 configured for some other target, in all respects, including output format
538 (choosing between ELF and ECOFF only), handling of pseudo-opcodes which may
539 generate debugging information or store symbol table information, and default
540 endianness. The available configuration names are:
547 The first two do not alter the default endianness from that of the primary
548 target for which the assembler was configured; the others change the default
549 to little- or big-endian as indicated by the
557 will override the endianness selection in any case.
559 This option is currently supported only when the primary target
561 is configured for is a mips ELF or ECOFF target. Furthermore, the primary
562 target or others specified with
563 .Li --enable-targets=...
564 at configuration time must include support for the other format, if both are
565 to be available. For example, the Irix 5 configuration includes support for
568 Eventually, this option will support more configurations, with more fine-grained
569 control over the assembler's behavior, and will be supported for more processors.
573 ignores this option. It is accepted for compatibility with the native tools.
579 Control how to deal with multiplication overflow and division by zero.
583 (which are synonyms) take a trap exception (and only work for Instruction
584 Set Architecture level 2 and higher);
588 (also synonyms, and the default) take a break exception.
591 When this option is used,
593 will issue a warning every time it generates a nop instruction from a macro.
596 .Ss Structure of this Manual
597 This manual is intended to describe what you need to know to use GNU
599 We cover the syntax expected in source files, including notation for symbols,
600 constants, and expressions; the directives that
602 understands; and of course how to invoke
605 We also cover special features in the machine specific configuration of
607 including assembler directives.
609 On the other hand, this manual is
611 intended as an introduction to programming in assembly language---let alone
612 programming in general! In a similar vein, we make no attempt to introduce
613 the machine architecture; we do
615 describe the instruction set, standard mnemonics, registers or addressing
616 modes that are standard to a particular architecture.
618 .Ss The GNU Assembler
621 is really a family of assemblers. This manual describes
623 a member of that family which is configured for the machine specific architectures.
624 If you use (or have used) the GNU assembler on one architecture, you should
625 find a fairly similar environment when you use it on another architecture.
626 Each version has much in common with the others, including object file formats,
627 most assembler directives (often called
629 and assembler syntax.
632 is primarily intended to assemble the output of the GNU C compiler
634 for use by the linker
636 Nevertheless, we've tried to make
638 assemble correctly everything that other assemblers for the same machine would
641 Unlike older assemblers,
643 is designed to assemble a source program in one pass of the source file. This
644 has a subtle impact on the
646 directive (see Section
649 .Ss Object File Formats
650 The GNU assembler can be configured to produce several alternative object
651 file formats. For the most part, this does not affect how you write assembly
652 language programs; but directives for debugging symbols are typically different
653 in different file formats.See Section
654 .Dq Symbol Attributes .
655 For the machine specific target,
657 is configured to produce ELF format object files.
660 After the program name
662 the command line may contain options and file names. Options may appear in
663 any order, and may be before, after, or between file names. The order of file
664 names is significant.
667 (two hyphens) by itself names the standard input file explicitly, as one of
674 any command line argument that begins with a hyphen (
676 is an option. Each option changes the behavior of
678 No option changes the way another option works. An option is a
680 followed by one or more letters; the case of the letter is important. All
681 options are optional.
683 Some options expect exactly one file name to follow them. The file name may
684 either immediately follow the option's letter (compatible with older assemblers)
685 or it may be the next command argument (GNU standard). These two command lines
688 .Bd -literal -offset indent
689 as -o my-object-file.o mumble.s
690 as -omy-object-file.o mumble.s
698 to describe the program input to one run of
700 The program may be in one or more files; how the source is partitioned into
701 files doesn't change the meaning of the source.
703 The source program is a concatenation of the text in all the files, in the
708 it assembles exactly one source program. The source program is made up of
709 one or more files. (The standard input is also a file.)
713 a command line that has zero or more input file names. The input files are
714 read (from left file name to right). A command line argument (in any position)
715 that has no special meaning is taken to be an input file name.
719 no file names it attempts to read one input file from the
721 standard input, which is normally your terminal. You may have to type ctl-D
724 there is no more program to assemble.
728 if you need to explicitly name the standard input file in your command line.
730 If the source is empty,
732 produces a small, empty object file.
734 .Em Filenames and Line-numbers
736 There are two ways of locating a line in the input file (or files) and either
737 may be used in reporting error messages. One way refers to a line number in
738 a physical file; the other refers to a line number in a \(lqlogical\(rq file.See Section
742 are those files named in the command line given to
746 are simply names declared explicitly by assembler directives; they bear no
747 relation to physical files. Logical file names help error messages reflect
748 the original source file, when
750 source is itself synthesized from other files.
754 directives emitted by the
756 preprocessor. See also File,,
760 .Ss Output (Object) File
763 it produces an output file, which is your assembly language program translated
764 into numbers. This file is the object file. Its default name is
766 You can give it another name by using the
768 option. Conventionally, object file names end with
770 The default name is used for historical reasons: older assemblers were capable
771 of assembling self-contained programs directly into a runnable program. (For
772 some formats, this isn't currently possible, but it can be done for the
776 The object file is meant for input to the linker
778 It contains assembled program code, information to help
780 integrate the assembled program into a runnable file, and (optionally) symbolic
781 information for the debugger.
783 .Ss Error and Warning Messages
785 may write warnings and error messages to the standard error file (usually
786 your terminal). This should not happen when a compiler runs
788 automatically. Warnings report an assumption made so that
790 could keep assembling a flawed program; errors report a grave problem that
793 Warning messages have the format
795 .Bd -literal -offset indent
796 file_name:NNN:Warning Message Text
801 is a line number). If a logical file name has been given (see Section
803 it is used for the filename, otherwise the name of the current input file
804 is used. If a logical line number was given then it is used to calculate the
805 number printed, otherwise the actual line in the current source file is printed.
806 The message text is intended to be self explanatory (in the grand Unix tradition).
808 Error messages have the format
809 .Bd -literal -offset indent
810 file_name:NNN:FATAL:Error Message Text
812 The file name and line number are derived as for warning messages. The actual
813 message text may be rather less explanatory because many of them aren't supposed
816 .Sh Command-Line Options
817 This chapter describes command-line options available in
819 versions of the GNU assembler; see Machine Dependencies, for options specific
820 to the machine specific target.
824 via the GNU C compiler, you can use the
826 option to pass arguments through to the assembler. The assembler arguments
827 must be separated from each other (and the
829 by commas. For example:
831 .Bd -literal -offset indent
832 gcc -c -g -O -Wa,-alh,-L file.c
835 This passes two options to the assembler:
837 (emit a listing to standard output with high-level and assembly source) and
839 (retain local symbols in the symbol table).
841 Usually you do not need to use this
843 mechanism, since many compiler command-line options are automatically passed
844 to the assembler by the compiler. (You can call the GNU compiler driver with
847 option to see precisely what options it passes to each compilation pass, including
850 .Ss Enable Listings: Op -a[cdhlns]
851 These options enable listing output from the assembler. By itself,
853 requests high-level, assembly, and symbols listing. You can use other letters
854 to select specific options for the list:
856 requests a high-level language listing,
858 requests an output-program assembly listing, and
860 requests a symbol table listing. High-level listings require that a compiler
861 debugging option like
863 be used, and that assembly listings (
869 option to omit false conditionals from a listing. Any lines which are not
870 assembled because of a false
874 or any other conditional), or a true
878 will be omitted from the listing.
882 option to omit debugging directives from the listing.
884 Once you have specified one of these options, you can further control listing
885 output and its appearance using the directives
895 option turns off all forms processing. If you do not request listing output
898 options, the listing-control directives have no effect.
902 may be combined into one option,
906 Note if the assembler source is coming from the standard input (e.g., because
907 it is being created by
911 command line switch is being used) then the listing will not contain any comments
912 or preprocessor directives. This is because the listing code buffers input
913 source lines from stdin only after they have been preprocessed by the assembler.
914 This reduces memory usage and makes the code more efficient.
917 Begin in alternate macro mode, see Altmacro,,
922 This option has no effect whatsoever, but it is accepted to make it more likely
923 that scripts written for other assemblers also work with
926 .Ss Work Faster: Op -f
928 should only be used when assembling programs written by a (trusted) compiler.
930 stops the assembler from doing whitespace and comment preprocessing on the
931 input file(s) before assembling them.See Section
938 when the files actually need to be preprocessed (if they contain comments,
941 does not work correctly.
944 .Ss Li .include Search Path: Op -I Va path
945 Use this option to add a
947 to the list of directories
949 searches for files specified in
951 directives (see Section
955 as many times as necessary to include a variety of paths. The current working
956 directory is always searched first; after that,
960 directories in the same order as they were specified (left to right) on the
963 .Ss Difference Tables: Op -K
964 On the machine specific family, this option is allowed, but has no effect.
965 It is permitted for compatibility with the GNU assembler on other platforms,
966 where it can be used to warn when the assembler alters the machine code generated
969 directives in difference tables. The machine specific family does not have
970 the addressing limitations that sometimes lead to this alteration on other
973 .Ss Include Local Symbols: Op -L
974 Symbols beginning with system-specific local label prefixes, typically
978 for traditional a.out systems, are called
980 See Section.Dq Symbol Names .
981 Normally you do not see such symbols when debugging, because they are intended
982 for the use of programs (like compilers) that compose assembler programs,
983 not for your notice. Normally both
987 discard such symbols, so you do not normally debug with them.
991 to retain those local symbols in the object file. Usually if you do this you
994 to preserve those symbols.
996 .Ss Configuring listing output: Op --listing
997 The listing feature of the assembler can be enabled via the command line switch
1001 This feature combines the input source file(s) with a hex dump of the corresponding
1002 locations in the output object file, and displays them as a listing file.
1003 The format of this listing can be controlled by directives inside the assembler
1021 and also by the following switches:
1024 .It --listing-lhs-width= Li number
1025 Sets the maximum width, in words, of the first line of the hex byte dump.
1026 This dump appears on the left hand side of the listing output.
1028 .It --listing-lhs-width2= Li number
1029 Sets the maximum width, in words, of any further lines of the hex byte dump
1030 for a given input source line. If this value is not specified, it defaults
1031 to being the same as the value specified for
1032 .Li --listing-lhs-width .
1033 If neither switch is used the default is to one.
1035 .It --listing-rhs-width= Li number
1036 Sets the maximum width, in characters, of the source line that is displayed
1037 alongside the hex dump. The default value for this parameter is 100. The source
1038 line is displayed on the right hand side of the listing output.
1040 .It --listing-cont-lines= Li number
1041 Sets the maximum number of continuation lines of hex dump that will be displayed
1042 for a given single line of source input. The default value is 4.
1045 .Ss Assemble in MRI Compatibility Mode: Op -M
1050 option selects MRI compatibility mode. This changes the syntax and pseudo-op
1053 to make it compatible with the
1057 (depending upon the configured target) assembler from Microtec Research. The
1058 exact nature of the MRI syntax will not be documented here; see the MRI manuals
1059 for more information. Note in particular that the handling of macros and macro
1060 arguments is somewhat different. The purpose of this option is to permit assembling
1061 existing MRI assembler code using
1064 The MRI compatibility is not complete. Certain operations of the MRI assembler
1065 depend upon its object file format, and can not be supported using other object
1066 file formats. Supporting these would require enhancing each object file format
1067 individually. These are:
1071 global symbols in common section
1073 The m68k MRI assembler supports common sections which are merged by the linker.
1074 Other object file formats do not support this.
1076 handles common sections by treating them as a single common symbol. It permits
1077 local symbols to be defined within a common section, but it can not support
1078 global symbols, since it has no way to describe them.
1083 The MRI assemblers support relocations against a negated section address,
1084 and relocations which combine the start addresses of two or more sections.
1085 These are not support by other object file formats.
1089 pseudo-op specifying start address
1093 pseudo-op permits the specification of a start address. This is not supported
1094 by other object file formats. The start address may instead be specified using
1097 option to the linker, or in a linker script.
1111 pseudo-ops assign a module name to the output file. This is not supported
1112 by other object file formats.
1120 pseudo-op begins an absolute section at a given address. This differs from
1124 pseudo-op, which changes the location within the current section. Absolute
1125 sections are not supported by other object file formats. The address of a
1126 section may be assigned within a linker script.
1129 There are some other features of the MRI assembler which are not supported
1132 typically either because they are difficult or because they seem of little
1133 consequence. Some of these may be supported in future releases.
1139 EBCDIC strings are not supported.
1142 packed binary coded decimal
1144 Packed binary coded decimal is not supported. This means that the
1148 pseudo-ops are not supported.
1156 pseudo-op is not supported.
1164 pseudo-op is not supported.
1168 branch control options
1172 branch control options---
1181 automatically relaxes all branches, whether forward or backward, to an appropriate
1182 size, so these options serve no purpose.
1186 list control options
1190 list control options are ignored:
1211 options are ignored:
1230 option is the default, unlike the MRI assembler.
1232 may be used to turn it off.
1240 pseudo-op is ignored.
1248 pseudo-op is not supported.
1256 pseudo-op is not supported.
1262 The various options of the i960
1264 pseudo-op are not supported.
1272 pseudo-op is not supported.
1280 pseudo-op is not supported.
1288 pseudo-op is not supported.
1291 .Ss Dependency Tracking: Op --MD
1293 can generate a dependency file for the file it creates. This file consists
1294 of a single rule suitable for
1296 describing the dependencies of the main source file.
1298 The rule is written to the file named in its argument.
1300 This feature is used in the automatic updating of makefiles.
1302 .Ss Name the Object File: Op -o
1303 There is always one object file output when you run
1305 By default it has the name
1307 You use this option (which takes exactly one filename) to give the object
1308 file a different name.
1310 Whatever the object file is called,
1312 overwrites any existing file of the same name.
1314 .Ss Join Data and Text Sections: Op -R
1318 to write the object file as if all data-section data lives in the text section.
1319 This is only done at the very last moment: your binary data are the same,
1320 but data section parts are relocated differently. The data section part of
1321 your object file is zero bytes long because all its bytes are appended to
1322 the text section. (See Section
1327 it would be possible to generate shorter address displacements (because we
1328 do not have to cross between text and data section). We refrain from doing
1329 this simply for compatibility with older versions of
1337 is configured for COFF or ELF output, this option is only useful if you use
1343 .Ss Display Assembly Statistics: Op --statistics
1346 to display two statistics about the resources used by
1348 the maximum amount of space allocated during the assembly (in bytes), and
1349 the total execution time taken for the assembly (in cpu seconds).
1351 .Ss Compatible Output: Op --traditional-format
1352 For some targets, the output of
1354 is different in some ways from the output of some existing assembler. This
1357 to use the traditional format instead.
1359 For example, it disables the exception frame optimizations which
1361 normally does by default on
1365 .Ss Announce Version: Op -v
1366 You can find out what version of as is running by including the option
1368 (which you can also spell as
1370 on the command line.
1372 .Ss Control Warnings: Op -W, Op --warn, Op --no-warn, Op --fatal-warnings
1374 should never give a warning or error message when assembling compiler output.
1375 But programs written by people often cause
1377 to give a warning that a particular assumption was made. All such warnings
1378 are directed to the standard error file.
1384 options, no warnings are issued. This only affects the warning messages: it
1385 does not change any particular of how
1387 assembles your file. Errors, which stop the assembly, are still reported.
1390 .Op --fatal-warnings
1393 considers files that generate warnings to be in error.
1395 You can switch these options off again by specifying
1397 which causes warnings to be output as usual.
1399 .Ss Generate Object File in Spite of Errors: Op -Z
1400 After an error message,
1402 normally produces no output. If for some reason you are interested in object
1403 file output even after
1405 gives an error message on your program, use the
1407 option. If there are any errors,
1409 continues anyways, and writes an object file after a final warning message
1411 .Li Va n errors, Va m warnings, generating bad object file.
1414 This chapter describes the machine-independent syntax allowed in a source
1417 syntax is similar to what many other assemblers use; it is inspired by the
1423 internal preprocessor:
1426 adjusts and removes extra whitespace. It leaves one space or tab before the
1427 keywords on a line, and turns any other whitespace on the line into a single
1431 removes all comments, replacing them with a single space, or an appropriate
1435 converts character constants into the appropriate numeric values.
1438 It does not do macro processing, include file handling, or anything else you
1439 may get from your C compiler's preprocessor. You can do include file processing
1442 directive (see Section
1444 You can use the GNU C compiler driver to get other \(lqCPP\(rq style preprocessing
1445 by giving the input file a
1448 .Dq Overall Options .
1450 Excess whitespace, comments, and character constants cannot be used in the
1451 portions of the input text that are not preprocessed.
1453 If the first line of an input file is
1457 option, whitespace and comments are not removed from the input file. Within
1458 an input file, you can ask for whitespace and comment removal in specific
1459 portions of the by putting a line that says
1461 before the text that may contain whitespace or comments, and putting a line
1464 after this text. This feature is mainly intend to support
1466 statements in compilers whose output is otherwise free of comments and whitespace.
1470 is one or more blanks or tabs, in any order. Whitespace is used to separate
1471 symbols, and to make programs neater for people to read. Unless within character
1472 constants (see Section
1474 any whitespace means the same as exactly one space.
1477 There are two ways of rendering comments to
1479 In both cases the comment is equivalent to one space.
1485 is a comment. This means you may not nest these comments.
1487 .Bd -literal -offset indent
1489 The only way to include a newline ('\en') in a comment
1490 is to use this sort of comment.
1493 /* This sort of comment does not nest. */
1498 character to the next newline is considered a comment and is ignored. The
1499 line comment character is
1503 on the i386 and x86-64;
1505 for Motorola PowerPC;
1507 on the SPARC; see Machine Dependencies.
1509 To be compatible with past assemblers, lines that begin with
1511 have a special interpretation. Following the
1513 should be an absolute expression (see Section
1515 the logical line number of the
1517 line. Then a string (see Section
1519 is allowed: if present it is a new logical file name. The rest of the line,
1520 if any, should be whitespace.
1522 If the first non-whitespace characters on the line are not numeric, the line
1523 is ignored. (Just like a comment.)
1525 .Bd -literal -offset indent
1526 # This is an ordinary comment.
1527 # 42-6 "new_file_name" # New logical file name
1528 # This is logical line # 36.
1530 This feature is deprecated, and may disappear from future versions of
1536 is one or more characters chosen from the set of all letters (both upper and
1537 lower case), digits and the three characters
1539 No symbol may begin with a digit. Case is significant. There is no length
1540 limit: all characters are significant. Symbols are delimited by characters
1541 not in that set, or by the beginning of a file (since the source program must
1542 end with a newline, the end of a file is not a possible symbol delimiter).See Section
1548 ends at a newline character (
1552 The newline or semicolon is considered part of the preceding statement. Newlines
1553 and semicolons within character constants are an exception: they do not end
1556 It is an error to end any statement with end-of-file: the last character of
1557 any input file should be a newline.
1559 An empty statement is allowed, and may include whitespace. It is ignored.
1561 A statement begins with zero or more labels, optionally followed by a key
1562 symbol which determines what kind of statement it is. The key symbol determines
1563 the syntax of the rest of the statement. If the symbol begins with a dot
1565 then the statement is an assembler directive: typically valid for any computer.
1566 If the symbol begins with a letter the statement is an assembly language
1568 it assembles into a machine language instruction.
1570 A label is a symbol immediately followed by a colon (
1572 Whitespace before a label or after a colon is permitted, but you may not have
1573 whitespace between a label's symbol and its colon.See Section
1576 .Bd -literal -offset indent
1577 label: .directive followed by something
1578 another_label: # This is an empty statement.
1579 instruction operand_1, operand_2, ...
1583 A constant is a number, written so that its value is known by inspection,
1584 without knowing any context. Like this:
1585 .Bd -literal -offset indent
1587 \&.byte 74, 0112, 092, 0x4A, 0X4a, 'J, '\eJ # All the same value.
1588 \&.ascii "Ring the bell\e7" # A string constant.
1589 \&.octa 0x123456789abcdef0123456789ABCDEF0 # A biGNUm.
1590 \&.float 0f-314159265358979323846264338327\e
1591 95028841971.693993751E-40 # - pi, a flonum.
1595 .Em Character Constants
1597 There are two kinds of character constants. A
1599 stands for one character in one byte and its value may be used in numeric
1600 expressions. String constants (properly called string
1602 are potentially many bytes and their values may not be used in arithmetic
1609 is written between double-quotes. It may contain double-quotes or null characters.
1610 The way to get special characters into a string is to
1612 these characters: precede them with a backslash
1614 character. For example
1616 represents one backslash: the first
1618 is an escape which tells
1620 to interpret the second character literally as a backslash (which prevents
1622 from recognizing the second
1624 as an escape character). The complete list of escapes follows.
1628 Mnemonic for backspace; for ASCII this is octal code 010.
1631 Mnemonic for FormFeed; for ASCII this is octal code 014.
1634 Mnemonic for newline; for ASCII this is octal code 012.
1637 Mnemonic for carriage-Return; for ASCII this is octal code 015.
1640 Mnemonic for horizontal Tab; for ASCII this is octal code 011.
1642 .It \e Va digit Va digit Va digit
1643 An octal character code. The numeric code is 3 octal digits. For compatibility
1644 with other Unix systems, 8 and 9 are accepted as digits: for example,
1646 has the value 010, and
1650 .It \e Li x Va hex-digits...
1651 A hex character code. All trailing hex digits are combined. Either upper or
1664 character. Needed in strings to represent this character, because an unescaped
1666 would end the string.
1668 .It \e Va anything-else
1669 Any other character when escaped by
1671 gives a warning, but assembles as if the
1673 was not present. The idea is that if you used an escape sequence you clearly
1674 didn't want the literal interpretation of the following character. However
1676 has no other interpretation, so
1678 knows it is giving you the wrong code and warns you of the fact.
1681 Which characters are escapable, and what those escapes represent, varies widely
1682 among assemblers. The current set is what we think the BSD 4.2 assembler recognizes,
1683 and is a subset of what most C compilers recognize. If you are in doubt, do
1684 not use an escape sequence.
1688 A single character may be written as a single quote immediately followed by
1689 that character. The same escapes apply to characters as to strings. So if
1690 you want to write the character backslash, you must write
1696 As you can see, the quote is an acute accent, not a grave accent. A newline
1699 immediately following an acute accent is taken as a literal character and
1700 does not count as the end of a statement. The value of a character constant
1701 in a numeric expression is the machine's byte-wide code for that character.
1703 assumes your character code is ASCII:
1707 means 66, and so on.
1709 .Em Number Constants
1712 distinguishes three kinds of numbers according to how they are stored in the
1715 are numbers that would fit into an
1719 are integers, but they are stored in more than 32 bits.
1721 are floating point numbers, described below.
1729 followed by zero or more of the binary digits
1734 followed by zero or more of the octal digits (
1737 A decimal integer starts with a non-zero digit followed by zero or more digits
1741 A hexadecimal integer is
1745 followed by one or more hexadecimal digits chosen from
1746 .Li 0123456789abcdefABCDEF .
1748 Integers have the usual values. To denote a negative integer, use the prefix
1751 discussed under expressions (see Section
1758 has the same syntax and semantics as an integer except that the number (or
1759 its negative) takes more than 32 bits to represent in binary. The distinction
1760 is made because in some places integers are permitted while biGNUms are not.
1766 represents a floating point number. The translation is indirect: a decimal
1767 floating point number from the text is converted by
1769 to a generic binary floating point number of more than sufficient precision.
1770 This generic floating point number is converted to a particular computer's
1771 floating point format (or formats) by a portion of
1773 specialized to that computer.
1775 A flonum is written by writing (in order)
1784 the rest of the number is a flonum.
1787 An optional sign: either
1795 zero or more decimal digits.
1799 .Em fractional part :
1801 followed by zero or more decimal digits.
1804 An optional exponent, consisting of:
1813 Optional sign: either
1818 One or more decimal digits.
1822 At least one of the integer part or the fractional part must be present. The
1823 floating point number has the usual base-10 value.
1826 does all processing using integers. Flonums are computed independently of
1827 any floating point hardware in the computer running
1830 .Sh Sections and Relocation
1832 Roughly, a section is a range of addresses, with no gaps; all data \(lqin\(rq those
1833 addresses is treated the same for some particular purpose. For example there
1834 may be a \(lqread only\(rq section.
1838 reads many object files (partial programs) and combines their contents to
1839 form a runnable program. When
1841 emits an object file, the partial program is assumed to start at address 0.
1843 assigns the final addresses for the partial program, so that different partial
1844 programs do not overlap. This is actually an oversimplification, but it suffices
1850 moves blocks of bytes of your program to their run-time addresses. These blocks
1851 slide to their run-time addresses as rigid units; their length does not change
1852 and neither does the order of bytes within them. Such a rigid unit is called
1855 Assigning run-time addresses to sections is called
1857 It includes the task of adjusting mentions of object-file addresses so they
1858 refer to the proper run-time addresses.
1860 An object file written by
1862 has at least three sections, any of which may be empty. These are named
1870 can also generate whatever other named sections you specify using the
1872 directive (see Section
1874 If you do not use any directives that place output in the
1878 sections, these sections still exist, but are empty.
1880 Within the object file, the text section starts at address
1882 the data section follows, and the bss section follows the data section.
1886 know which data changes when the sections are relocated, and how to change
1889 also writes to the object file details of the relocation needed. To perform
1892 must know, each time an address in the object file is mentioned:
1895 Where in the object file is the beginning of this reference to an address?
1897 How long (in bytes) is this reference?
1899 Which section does the address refer to? What is the numeric value of
1900 .Bd -filled -offset indent
1904 .Va start-address of section ) ?
1907 Is the reference to an address \(lqProgram-Counter relative\(rq?
1910 In fact, every address
1912 ever uses is expressed as
1913 .Bd -filled -offset indent
1917 .Va offset into section )
1919 Further, most expressions
1921 computes have this section-relative nature.
1923 In this manual we use the notation {
1932 Apart from text, data and bss sections you need to know about the
1936 mixes partial programs, addresses in the absolute section remain unchanged.
1937 For example, address
1939 is \(lqrelocated\(rq to run-time address 0 by
1941 Although the linker never arranges two partial programs' data sections with
1942 overlapping addresses after linking,
1944 their absolute sections must overlap. Address
1946 in one part of a program is always the same address when the program is running
1949 in any other part of the program.
1951 The idea of sections is extended to the
1953 section. Any address whose section is unknown at assembly time is by definition
1958 is filled in later. Since numbers are always defined, the only way to generate
1959 an undefined address is to mention an undefined symbol. A reference to a named
1960 common block would be such a symbol: its value is unknown at assembly time
1966 is used to describe groups of sections in the linked program.
1968 puts all partial programs' text sections in contiguous addresses in the linked
1969 program. It is customary to refer to the
1971 of a program, meaning all the addresses of all partial programs' text sections.
1972 Likewise for data and bss sections.
1974 Some sections are manipulated by
1976 others are invented for use of
1978 and have no meaning except during assembly.
1982 deals with just four kinds of sections, summarized below.
1986 These sections hold your program.
1990 treat them as separate but equal sections. Anything you can say of one section
1991 is true of another. When the program is running, however, it is customary
1992 for the text section to be unalterable. The text section is often shared among
1993 processes: it contains instructions, constants and the like. The data section
1994 of a running program is usually alterable: for example, C variables would
1995 be stored in the data section.
1998 This section contains zeroed bytes when your program begins running. It is
1999 used to hold uninitialized variables or common storage. The length of each
2000 partial program's bss section is important, but because it starts out containing
2001 zeroed bytes there is no need to store explicit zero bytes in the object file.
2002 The bss section was invented to eliminate those explicit zeros from object
2005 .It absolute section
2006 Address 0 of this section is always \(lqrelocated\(rq to runtime address 0. This is
2007 useful if you want to refer to an address that
2009 must not change when relocating. In this sense we speak of absolute addresses
2010 being \(lqunrelocatable\(rq: they do not change during relocation.
2012 .It undefined section
2013 This \(lqsection\(rq is a catch-all for address references to objects not in the preceding
2017 An idealized example of three relocatable sections follows. The example uses
2018 the traditional section names
2022 Memory addresses are on the horizontal axis.
2024 .Bd -literal -offset indent
2026 partial program # 1: |ttttt|dddd|00|
2033 partial program # 2: |TTT|DDD|000|
2036 +--+---+-----+--+----+---+-----+~~
2037 linked program: | |TTT|ttttt| |dddd|DDD|00000|
2038 +--+---+-----+--+----+---+-----+~~
2043 .Ss Assembler Internal Sections
2044 These sections are meant only for the internal use of
2046 They have no meaning at run-time. You do not really need to know about these
2047 sections for most purposes; but they can be mentioned in
2049 warning messages, so it might be helpful to have an idea of their meanings
2052 These sections are used to permit the value of every expression in your assembly
2053 language program to be a section-relative address.
2056 .It ASSEMBLER-INTERNAL-LOGIC-ERROR!
2057 An internal assembler logic error has been found. This means there is a bug
2061 The assembler stores complex expression internally as combinations of symbols.
2062 When it needs to represent an expression as a symbol, it puts it in the expr
2067 You may have separate groups of data in named sections that you want to end
2068 up near to each other in the object file, even though they are not contiguous
2069 in the assembler source.
2073 for this purpose. Within each section, there can be numbered subsections with
2074 values from 0 to 8192. Objects assembled into the same subsection go into
2075 the object file together with other objects in the same subsection. For example,
2076 a compiler might want to store constants in the text section, but might not
2077 want to have them interspersed with the program being assembled. In this case,
2078 the compiler could issue a
2080 before each section of code being output, and a
2082 before each group of constants being output.
2084 Subsections are optional. If you do not use subsections, everything goes in
2085 subsection number zero.
2087 Subsections appear in your object file in numeric order, lowest numbered to
2088 highest. (All this to be compatible with other people's assemblers.) The object
2089 file contains no representation of subsections;
2091 and other programs that manipulate object files see no trace of them. They
2092 just see all your text subsections as a text section, and all your data subsections
2095 To specify which subsection you want subsequent statements assembled into,
2096 use a numeric argument to specify it, in a
2097 .Li .text Va expression
2099 .Li .data Va expression
2100 statement. You can also use the
2102 directive (see Section
2104 to specify a subsection:
2105 .Li .subsection Va expression .
2107 should be an absolute expression (see Section
2113 is assumed. Likewise
2120 .Bd -literal -offset indent
2121 \&.text 0 # The default subsection is text 0 anyway.
2122 \&.ascii "This lives in the first text subsection. *"
2124 \&.ascii "But this lives in the second text subsection."
2126 \&.ascii "This lives in the data section,"
2127 \&.ascii "in the first data subsection."
2129 \&.ascii "This lives in the first text section,"
2130 \&.ascii "immediately following the asterisk (*)."
2134 .Em location counter
2135 incremented by one for every byte assembled into that section. Because subsections
2136 are merely a convenience restricted to
2138 there is no concept of a subsection location counter. There is no way to directly
2139 manipulate a location counter---but the
2141 directive changes it, and any label definition captures its current value.
2142 The location counter of the section where statements are being assembled is
2148 The bss section is used for local common variable storage. You may allocate
2149 address space in the bss section, but you may not dictate data to load into
2150 it before your program executes. When your program starts running, all the
2151 contents of the bss section are zeroed bytes.
2155 pseudo-op defines a symbol in the bss section; see Lcomm,,
2161 pseudo-op may be used to declare a common symbol, which is another form of
2162 uninitialized symbol; see Comm,,
2167 Symbols are a central concept: the programmer uses symbols to name things,
2168 the linker uses symbols to link, and the debugger uses symbols to debug.
2173 does not place symbols in the object file in the same order they were declared.
2174 This may break some debuggers.
2180 is written as a symbol immediately followed by a colon
2182 The symbol then represents the current value of the active location counter,
2183 and is, for example, a suitable instruction operand. You are warned if you
2184 use the same symbol to represent two different locations: the first definition
2185 overrides any other definitions.
2187 .Ss Giving Symbols Other Values
2188 A symbol can be given an arbitrary value by writing a symbol, followed by
2191 followed by an expression (see Section
2193 This is equivalent to using the
2195 directive.See Section
2197 In the same way, using a double equals sign
2200 here represents an equivalent of the
2202 directive.See Section
2206 Symbol names begin with a letter or with one of
2208 On most machines, you can also use
2210 in symbol names; exceptions are noted in Machine Dependencies. That character
2211 may be followed by any string of digits, letters, dollar signs (unless otherwise
2212 noted for a particular target machine), and underscores.
2214 Case of letters is significant:
2216 is a different symbol name than
2219 Each symbol has exactly one name. Each name in an assembly language program
2220 refers to exactly one symbol. You may use that symbol name any number of times
2223 .Em Local Symbol Names
2225 A local symbol is any symbol beginning with certain local label prefixes.
2226 By default, the local label prefix is
2230 for traditional a.out systems, but each target may have its own set of local
2233 Local symbols are defined and used within the assembler, but they are normally
2234 not saved in object files. Thus, they are not visible when debugging. You
2239 to retain the local symbols in the object files.
2243 Local labels help compilers and programmers use names temporarily. They create
2244 symbols which are guaranteed to be unique over the entire scope of the input
2245 source code and which can be referred to by a simple notation. To define a
2246 local label, write a label of the form
2250 represents any positive integer). To refer to the most recent previous definition
2253 using the same number as when you defined the label. To refer to the next
2254 definition of a local label, write
2258 stands for \(lqbackwards\(rq and the
2260 stands for \(lqforwards\(rq.
2262 There is no restriction on how you can use these labels, and you can reuse
2263 them too. So that it is possible to repeatedly define the same local label
2264 (using the same number
2266 although you can only refer to the most recently defined local label of that
2267 number (for a backwards reference) or the next definition of a specific local
2268 label for a forward reference. It is also worth noting that the first 10 local
2272 are implemented in a slightly more efficient manner than the others.
2276 .Bd -literal -offset indent
2283 Which is the equivalent of:
2285 .Bd -literal -offset indent
2286 label_1: branch label_3
2287 label_2: branch label_1
2288 label_3: branch label_4
2289 label_4: branch label_3
2292 Local label names are only a notational device. They are immediately transformed
2293 into more conventional symbol names before the assembler uses them. The symbol
2294 names are stored in the symbol table, appear in error messages, and are optionally
2295 emitted to the object file. The names are constructed using these parts:
2298 .It Em local label prefix
2299 All local symbols begin with the system-specific local label prefix. Normally
2304 forget symbols that start with the local label prefix. These labels are used
2305 for symbols you are never intended to see. If you use the
2309 retains these symbols in the object file. If you also instruct
2311 to retain these symbols, you may use them in debugging.
2314 This is the number that was used in the local label definition. So if the
2321 This unusual character is included so you do not accidentally invent a symbol
2322 of the same name. The character has ASCII value of
2326 .It Em ordinal number
2327 This is a serial number to keep the labels distinct. The first definition
2332 The 15th definition of
2336 and so on. Likewise the first definition of
2340 and its 15th definition gets
2345 So for example, the first
2354 .Em Dollar Local Labels
2357 also supports an even more local form of local labels called dollar labels.
2358 These labels go out of scope (i.e., they become undefined) as soon as a non-local
2359 label is defined. Thus they remain valid for only a small region of the input
2360 source code. Normal local labels, by contrast, remain in scope for the entire
2361 file, or until they are redefined by another occurrence of the same local
2364 Dollar labels are defined in exactly the same way as ordinary local labels,
2365 except that instead of being terminated by a colon, they are terminated by
2366 a dollar sign, e.g.,
2369 They can also be distinguished from ordinary local labels by their transformed
2370 names which use ASCII character
2372 (control-A) as the magic character to distinguish them from ordinary labels.
2373 For example, the fifth definition of
2378 .Ss The Special Dot Symbol
2381 refers to the current address that
2383 is assembling into. Thus, the expression
2387 to contain its own address. Assigning a value to
2389 is treated the same as a
2391 directive. Thus, the expression
2393 is the same as saying
2396 .Ss Symbol Attributes
2397 Every symbol has, as well as its name, the attributes \(lqValue\(rq and \(lqType\(rq. Depending
2398 on output format, symbols can also have auxiliary attributes. The detailed
2402 If you use a symbol without defining it,
2404 assumes zero for all these attributes, and probably won't warn you. This makes
2405 the symbol an externally defined symbol, which is generally what you would
2410 The value of a symbol is (usually) 32 bits. For a symbol which labels a location
2411 in the text, data, bss or absolute sections the value is the number of addresses
2412 from the start of that section to the label. Naturally for text, data and
2413 bss sections the value of a symbol changes as
2415 changes section base addresses during linking. Absolute symbols' values do
2416 not change during linking: that is why they are called absolute.
2418 The value of an undefined symbol is treated in a special way. If it is 0 then
2419 the symbol is not defined in this assembler source file, and
2421 tries to determine its value from other files linked into the same program.
2422 You make this kind of symbol simply by mentioning a symbol name without defining
2423 it. A non-zero value represents a
2425 common declaration. The value is how much common storage to reserve, in bytes
2426 (addresses). The symbol refers to the first address of the allocated storage.
2430 The type attribute of a symbol contains relocation (section) information,
2431 any flag settings indicating that a symbol is external, and (optionally),
2432 other information for linkers and debuggers. The exact format depends on the
2433 object-code output format in use.
2438 specifies an address or numeric value. Whitespace may precede and/or follow
2441 The result of an expression must be an absolute number, or else an offset
2442 into a particular section. If an expression is not absolute, and there is
2443 not enough information when
2445 sees the expression to know its section, a second pass over the source program
2446 might be necessary to interpret the expression---but the second pass is currently
2449 aborts with an error message in this situation.
2451 .Ss Empty Expressions
2452 An empty expression has no value: it is just whitespace or null. Wherever
2453 an absolute expression is required, you may omit the expression, and
2455 assumes a value of (absolute) 0. This is compatible with other assemblers.
2457 .Ss Integer Expressions
2459 .Em integer expression
2468 are symbols, numbers or subexpressions. In other contexts arguments are sometimes
2469 called \(lqarithmetic operands\(rq. In this manual, to avoid confusing them with the
2470 \(lqinstruction operands\(rq of the machine language, we use the term \(lqargument\(rq to
2471 refer to parts of expressions only, reserving the word \(lqoperand\(rq to refer only
2472 to machine instruction operands.
2474 Symbols are evaluated to yield {
2479 is one of text, data, bss, absolute, or undefined.
2481 is a signed, 2's complement 32 bit integer.
2483 Numbers are usually integers.
2485 A number can be a flonum or biGNUm. In this case, you are warned that only
2486 the low order 32 bits are used, and
2488 pretends these 32 bits are an integer. You may write integer-manipulating
2489 instructions that act on exotic constants, compatible with other assemblers.
2491 Subexpressions are a left parenthesis
2493 followed by an integer expression, followed by a right parenthesis
2495 or a prefix operator followed by an argument.
2500 are arithmetic functions, like
2504 Prefix operators are followed by an argument. Infix operators appear between
2505 their arguments. Operators may be preceded and/or followed by whitespace.
2511 .Em prefix operators .
2512 They each take one argument, which must be absolute.
2517 Two's complement negation.
2519 .Em Complementation .
2526 take two arguments, one on either side. Operators have precedence, but operations
2527 with equal precedence are performed left to right. Apart from
2531 both arguments must be absolute, and the result is absolute.
2539 .Em Multiplication .
2543 Truncation is the same as the C operator
2551 Same as the C operator
2556 Same as the C operator
2561 Intermediate precedence
2566 .Em Bitwise Inclusive Or .
2572 .Em Bitwise Exclusive Or .
2575 .Em Bitwise Or Not .
2584 If either argument is absolute, the result has the section of the other argument.
2585 You may not add together arguments from different sections.
2589 If the right argument is absolute, the result has the section of the left
2590 argument. If both arguments are in the same section, the result is absolute.
2591 You may not subtract arguments from different sections.
2603 .Em Is Greater Than Or Equal To
2605 .Em Is Less Than Or Equal To
2607 The comparison operators can be used as infix operators. A true results has
2608 a value of -1 whereas a false result has a value of 0. Note, these operators
2609 perform signed comparisons.
2622 These two logical operations can be used to combine the results of sub expressions.
2623 Note, unlike the comparison operators a true result returns a value of 1 but
2624 a false results does still return 0. Also note that the logical or operator
2625 has a slightly lower precedence than logical and.
2629 In short, it's only meaningful to add or subtract the
2631 in an address; you can only have a defined section in one of the two arguments.
2633 .Sh Assembler Directives
2634 All assembler directives have names that begin with a period (
2636 The rest of the name is letters, usually in lower case.
2638 This chapter discusses directives that are available regardless of the target
2639 machine configuration for the GNU assembler.
2642 This directive stops the assembly immediately. It is for compatibility with
2643 other assemblers. The original idea was that the assembly language source
2644 would be piped into the assembler. If the sender of the source quit, it could
2645 use this directive tells
2647 to quit also. One day
2649 will not be supported.
2651 .Ss Li .align Va abs-expr, Va abs-expr, Va abs-expr
2652 Pad the location counter (in the current subsection) to a particular storage
2653 boundary. The first expression (which must be absolute) is the alignment required,
2656 The second expression (also absolute) gives the fill value to be stored in
2657 the padding bytes. It (and the comma) may be omitted. If it is omitted, the
2658 padding bytes are normally zero. However, on some systems, if the section
2659 is marked as containing code and the fill value is omitted, the space is filled
2660 with no-op instructions.
2662 The third expression is also absolute, and is also optional. If it is present,
2663 it is the maximum number of bytes that should be skipped by this alignment
2664 directive. If doing the alignment would require skipping more bytes than the
2665 specified maximum, then the alignment is not done at all. You can omit the
2666 fill value (the second argument) entirely by simply using two commas after
2667 the required alignment; this can be useful if you want the alignment to be
2668 filled with no-op instructions when appropriate.
2670 The way the required alignment is specified varies from system to system.
2671 For the arc, hppa, i386 using ELF, i860, iq2000, m68k, or32, s390, sparc,
2672 tic4x, tic80 and xtensa, the first expression is the alignment request in
2675 advances the location counter until it is a multiple of 8. If the location
2676 counter is already a multiple of 8, no change is needed. For the tic54x, the
2677 first expression is the alignment request in words.
2679 For other systems, including the i386 using a.out format, and the arm and
2680 strongarm, it is the number of low-order zero bits the location counter must
2681 have after advancement. For example
2683 advances the location counter until it a multiple of 8. If the location counter
2684 is already a multiple of 8, no change is needed.
2686 This inconsistency is due to the different behaviors of the various native
2687 assemblers for these systems which GAS must emulate. GAS also provides
2691 directives, described later, which have a consistent behavior across all architectures
2692 (but are specific to GAS).
2694 .Ss Li .ascii " Va string"...
2696 expects zero or more string literals (see Section
2698 separated by commas. It assembles each string (with no automatic trailing
2699 zero byte) into consecutive addresses.
2701 .Ss Li .asciz " Va string"...
2705 but each string is followed by a zero byte. The \(lqz\(rq in
2707 stands for \(lqzero\(rq.
2709 .Ss Li .balign[wl] Va abs-expr, Va abs-expr, Va abs-expr
2710 Pad the location counter (in the current subsection) to a particular storage
2711 boundary. The first expression (which must be absolute) is the alignment request
2712 in bytes. For example
2714 advances the location counter until it is a multiple of 8. If the location
2715 counter is already a multiple of 8, no change is needed.
2717 The second expression (also absolute) gives the fill value to be stored in
2718 the padding bytes. It (and the comma) may be omitted. If it is omitted, the
2719 padding bytes are normally zero. However, on some systems, if the section
2720 is marked as containing code and the fill value is omitted, the space is filled
2721 with no-op instructions.
2723 The third expression is also absolute, and is also optional. If it is present,
2724 it is the maximum number of bytes that should be skipped by this alignment
2725 directive. If doing the alignment would require skipping more bytes than the
2726 specified maximum, then the alignment is not done at all. You can omit the
2727 fill value (the second argument) entirely by simply using two commas after
2728 the required alignment; this can be useful if you want the alignment to be
2729 filled with no-op instructions when appropriate.
2735 directives are variants of the
2739 directive treats the fill pattern as a two byte word value. The
2741 directives treats the fill pattern as a four byte longword value. For example,
2742 .Li .balignw 4,0x368d
2743 will align to a multiple of 4. If it skips two bytes, they will be filled
2744 in with the value 0x368d (the exact placement of the bytes depends upon the
2745 endianness of the processor). If it skips 1 or 3 bytes, the fill value is
2748 .Ss Li .byte Va expressions
2750 expects zero or more expressions, separated by commas. Each expression is
2751 assembled into the next byte.
2753 .Ss Li .comm Va symbol , Va length
2755 declares a common symbol named
2757 When linking, a common symbol in one object file may be merged with a defined
2758 or common symbol of the same name in another object file. If
2760 does not see a definition for the symbol--just one or more common symbols--then
2763 bytes of uninitialized memory.
2765 must be an absolute expression. If
2767 sees multiple common symbols with the same name, and they do not all have
2768 the same size, it will allocate space using the largest size.
2772 directive takes an optional third argument. This is the desired alignment
2773 of the symbol, specified as a byte boundary (for example, an alignment of
2774 16 means that the least significant 4 bits of the address should be zero).
2775 The alignment must be an absolute expression, and it must be a power of two.
2778 allocates uninitialized memory for the common symbol, it will use the alignment
2779 when placing the symbol. If no alignment is specified,
2781 will set the alignment to the largest power of two less than or equal to the
2782 size of the symbol, up to a maximum of 16.
2784 .Ss Li .cfi_startproc [simple]
2786 is used at the beginning of each function that should have an entry in
2788 It initializes some internal data structures. Don't forget to close the function
2794 is used along with parameter
2796 it also emits some architecture dependent initial CFI instructions.
2799 is used at the end of a function where it closes its unwind entry previously
2801 .Li .cfi_startproc ,
2805 .Ss Li .cfi_personality Va encoding [, Va exp]
2806 .Li .cfi_personality
2807 defines personality routine and its encoding.
2809 must be a constant determining how the personality should be encoded. If it
2811 .Li DW_EH_PE_omit ) ,
2812 second argument is not present, otherwise second argument should be a constant
2813 or a symbol name. When using indirect encodings, the symbol provided should
2814 be the location where personality can be loaded from, not the personality
2815 routine itself. The default after
2818 .Li .cfi_personality 0xff ,
2819 no personality routine.
2821 .Ss Li .cfi_lsda Va encoding [, Va exp]
2823 defines LSDA and its encoding.
2825 must be a constant determining how the LSDA should be encoded. If it is 255
2827 .Li DW_EH_PE_omit ) ,
2828 second argument is not present, otherwise second argument should be a constant
2829 or a symbol name. The default after
2832 .Li .cfi_lsda 0xff ,
2835 .Ss Li .cfi_def_cfa Va register, Va offset
2837 defines a rule for computing CFA as:
2838 .Em take address from Va register and add Va offset to it .
2840 .Ss Li .cfi_def_cfa_register Va register
2841 .Li .cfi_def_cfa_register
2842 modifies a rule for computing CFA. From now on
2844 will be used instead of the old one. Offset remains the same.
2846 .Ss Li .cfi_def_cfa_offset Va offset
2847 .Li .cfi_def_cfa_offset
2848 modifies a rule for computing CFA. Register remains the same, but
2850 is new. Note that it is the absolute offset that will be added to a defined
2851 register to compute CFA address.
2853 .Ss Li .cfi_adjust_cfa_offset Va offset
2855 .Li .cfi_def_cfa_offset
2858 is a relative value that is added/substracted from the previous offset.
2860 .Ss Li .cfi_offset Va register, Va offset
2867 .Ss Li .cfi_rel_offset Va register, Va offset
2872 from the current CFA register. This is transformed to
2874 using the known displacement of the CFA register from the CFA. This is often
2875 easier to use, because the number will match the code it's annotating.
2877 .Ss Li .cfi_register Va register1, Va register2
2880 is saved in register
2883 .Ss Li .cfi_restore Va register
2885 says that the rule for
2887 is now the same as it was at the beginning of the function, after all initial
2888 instruction added by
2892 .Ss Li .cfi_undefined Va register
2893 From now on the previous value of
2895 can't be restored anymore.
2897 .Ss Li .cfi_same_value Va register
2900 is the same like in the previous frame, i.e. no restoration needed.
2902 .Ss Li .cfi_remember_state,
2903 First save all current rules for all registers by
2904 .Li .cfi_remember_state ,
2905 then totally screw them up by subsequent
2907 directives and when everything is hopelessly bad, use
2908 .Li .cfi_restore_state
2909 to restore the previous saved state.
2911 .Ss Li .cfi_return_column Va register
2912 Change return column
2914 i.e. the return address is either directly in
2916 or can be accessed by rules for
2919 .Ss Li .cfi_signal_frame
2920 Mark current function as signal trampoline.
2922 .Ss Li .cfi_window_save
2923 SPARC register window has been saved.
2925 .Ss Li .cfi_escape Va expression[, ...]
2926 Allows the user to add arbitrary bytes to the unwind info. One might use this
2927 to add OS-specific CFI opcodes, or generic CFI opcodes that GAS does not yet
2930 .Ss Li .file Va fileno Va filename
2931 When emitting dwarf2 line number information
2933 assigns filenames to the
2935 file name table. The
2937 operand should be a unique positive integer to use as the index of the entry
2940 operand is a C string literal.
2942 The detail of filename indices is exposed to the user because the filename
2943 table is shared with the
2945 section of the dwarf2 debugging information, and thus the user must know the
2946 exact indices that table entries will have.
2948 .Ss Li .loc Va fileno Va lineno [ Va column] [ Va options]
2951 directive will add row to the
2953 line number matrix corresponding to the immediately following assembly instruction.
2959 arguments will be applied to the
2961 state machine before the row is added.
2965 are a sequence of the following tokens in any order:
2969 This option will set the
2977 This option will set the
2985 This option will set the
2992 .It is_stmt Va value
2993 This option will set the
2999 which must be either 0 or 1.
3002 This directive will set the
3008 which must be an unsigned integer.
3011 .Ss Li .loc_mark_blocks Va enable
3013 .Li .loc_mark_blocks
3014 directive makes the assembler emit an entry to the
3016 line number matrix with the
3018 register in the state machine set whenever a code label is seen. The
3020 argument should be either 1 or 0, to enable or disable this function respectively.
3022 .Ss Li .data Va subsection
3026 to assemble the following statements onto the end of the data subsection numbered
3028 (which is an absolute expression). If
3030 is omitted, it defaults to zero.
3032 .Ss Li .double Va flonums
3034 expects zero or more flonums, separated by commas. It assembles floating point
3038 Force a page break at this point, when generating assembly listings.
3044 support for conditional assembly; see If,,
3046 \&. It marks the beginning of a section of code to be assembled if the condition
3055 support for conditional assembly; see If,,
3057 \&. It is shorthand for beginning a new
3059 block that would otherwise fill the entire
3065 marks the end of the assembly file.
3067 does not process anything in the file past the
3073 marks the end of a function specified with
3080 support for conditional assembly; it marks the end of a block of code that
3081 is only assembled conditionally.See Section
3084 .Ss Li .equ Va symbol, Va expression
3085 This directive sets the value of
3089 It is synonymous with
3095 .Ss Li .equiv Va symbol, Va expression
3102 except that the assembler will signal an error if
3104 is already defined. Note a symbol which has been referenced but not actually
3105 defined is considered to be undefined.
3107 Except for the contents of the error message, this is roughly equivalent to
3108 .Bd -literal -offset indent
3114 plus it protects the symbol from later redefinition.
3116 .Ss Li .eqv Va symbol, Va expression
3121 but no attempt is made to evaluate the expression or any part of it immediately.
3122 Instead each time the resulting symbol is used in an expression, a snapshot
3123 of its current value is taken.
3130 directive, it will print an error message and, unless the
3132 option was used, it will not generate an object file. This can be used to
3133 signal an error in conditionally compiled code.
3135 .Ss Li .error " Va string"
3138 this directive emits an error, but you can specify a string that will be emitted
3139 as the error message. If you don't specify the message, it defaults to
3140 .Li ".error directive invoked in source file" .
3141 See Section.Dq Errors .
3143 .Bd -literal -offset indent
3144 .error "This code has not been assembled and tested."
3148 Exit early from the current macro definition.See Section
3153 is accepted in the source program---for compatibility with other assemblers---but
3156 treats all undefined symbols as external.
3158 .Ss Li .fail Va expression
3159 Generates an error or a warning. If the value of the
3163 will print a warning message. If the value is less than 500,
3165 will print an error message. The message will include the value of
3167 This can occasionally be useful inside complex nested macros or conditional
3170 .Ss Li .file Va string
3174 that we are about to start a new logical file.
3176 is the new file name. In general, the filename is recognized whether or not
3177 it is surrounded by quotes
3179 but if you wish to specify an empty file name, you must give the quotes--
3181 This statement may go away in future: it is only recognized to be compatible
3186 .Ss Li .fill Va repeat , Va size , Va value
3191 are absolute expressions. This emits
3197 may be zero or more.
3199 may be zero or more, but if it is more than 8, then it is deemed to have the
3200 value 8, compatible with other people's assemblers. The contents of each
3202 bytes is taken from an 8-byte number. The highest order 4 bytes are zero.
3203 The lowest order 4 bytes are
3205 rendered in the byte-order of an integer on the computer
3207 is assembling for. Each
3209 bytes in a repetition is taken from the lowest order
3211 bytes of this number. Again, this bizarre behavior is compatible with other
3212 people's assemblers.
3217 are optional. If the second comma and
3221 is assumed zero. If the first comma and following tokens are absent,
3225 .Ss Li .float Va flonums
3226 This directive assembles zero or more flonums, separated by commas. It has
3230 .Ss Li .func Va name[, Va label]
3232 emits debugging information to denote function
3234 and is ignored unless the file is assembled with debugging enabled. Only
3236 is currently supported.
3238 is the entry point of the function and if omitted
3246 or nothing, depending on the target. All functions are currently defined to
3249 return type. The function must be terminated with
3252 .Ss Li .global Va symbol, Li .globl Va symbol
3254 makes the symbol visible to
3258 in your partial program, its value is made available to other partial programs
3259 that are linked with it. Otherwise,
3261 takes its attributes from a symbol of the same name from another file linked
3262 into the same program.
3268 are accepted, for compatibility with other assemblers.
3270 .Ss Li .hidden Va names
3271 This is one of the ELF visibility directives. The other two are
3280 This directive overrides the named symbols default visibility (which is set
3281 by their binding: local, global or weak). The directive sets the visibility
3284 which means that the symbols are not visible to other components. Such symbols
3285 are always considered to be
3289 .Ss Li .hword Va expressions
3290 This expects zero or more
3292 and emits a 16 bit number for each.
3294 This directive is a synonym for
3298 This directive is used by some assemblers to place tags in object files. The
3299 behavior of this directive varies depending on the target. When using the
3300 a.out object file format,
3302 simply accepts the directive for source-file compatibility with existing assemblers,
3303 but does not emit anything for it. When using COFF, comments are emitted to
3308 section, depending on the target. When using ELF, comments are emitted to
3313 .Ss Li .if Va absolute expression
3315 marks the beginning of a section of code which is only considered part of
3316 the source program being assembled if the argument (which must be an
3317 .Va absolute expression )
3318 is non-zero. The end of the conditional section of code must be marked by
3322 optionally, you may include code for the alternative condition, flagged by
3326 If you have several conditions to check,
3328 may be used to avoid nesting blocks if/else within each subsequent
3332 The following variants of
3336 .It .ifdef Va symbol
3337 Assembles the following section of code if the specified
3339 has been defined. Note a symbol which has been referenced but not yet defined
3340 is considered to be undefined.
3343 Assembles the following section of code if the operand is blank (empty).
3345 .It .ifc Va string1, Va string2
3346 Assembles the following section of code if the two strings are the same. The
3347 strings may be optionally quoted with single quotes. If they are not quoted,
3348 the first string stops at the first comma, and the second string stops at
3349 the end of the line. Strings which contain whitespace should be quoted. The
3350 string comparison is case sensitive.
3352 .It .ifeq Va absolute expression
3353 Assembles the following section of code if the argument is zero.
3355 .It .ifeqs Va string1, Va string2
3358 The strings must be quoted using double quotes.
3360 .It .ifge Va absolute expression
3361 Assembles the following section of code if the argument is greater than or
3364 .It .ifgt Va absolute expression
3365 Assembles the following section of code if the argument is greater than zero.
3367 .It .ifle Va absolute expression
3368 Assembles the following section of code if the argument is less than or equal
3371 .It .iflt Va absolute expression
3372 Assembles the following section of code if the argument is less than zero.
3377 but the sense of the test is reversed: this assembles the following section
3378 of code if the operand is non-blank (non-empty).
3380 .It .ifnc Va string1, Va string2.
3383 but the sense of the test is reversed: this assembles the following section
3384 of code if the two strings are not the same.
3386 .It .ifndef Va symbol
3387 .It .ifnotdef Va symbol
3388 Assembles the following section of code if the specified
3390 has not been defined. Both spelling variants are equivalent. Note a symbol
3391 which has been referenced but not yet defined is considered to be undefined.
3393 .It .ifne Va absolute expression
3394 Assembles the following section of code if the argument is not equal to zero
3395 (in other words, this is equivalent to
3398 .It .ifnes Va string1, Va string2
3401 but the sense of the test is reversed: this assembles the following section
3402 of code if the two strings are not the same.
3405 .Ss Li .incbin " Va file"[, Va skip[, Va count]]
3410 verbatim at the current location. You can control the search paths used with
3413 command-line option (see Section
3415 Quotation marks are required around
3420 argument skips a number of bytes from the start of the
3424 argument indicates the maximum number of bytes to read. Note that the data
3425 is not aligned in any way, so it is the user's responsibility to make sure
3426 that proper alignment is provided both before and after the
3430 .Ss Li .include " Va file"
3431 This directive provides a way to include supporting files at specified points
3432 in your source program. The code from
3434 is assembled as if it followed the point of the
3436 when the end of the included file is reached, assembly of the original file
3437 continues. You can control the search paths used with the
3439 command-line option (see Section
3441 Quotation marks are required around
3444 .Ss Li .int Va expressions
3447 of any section, separated by commas. For each expression, emit a number that,
3448 at run time, is the value of that expression. The byte order and bit size
3449 of the number depends on what kind of target the assembly is for.
3451 .Ss Li .internal Va names
3452 This is one of the ELF visibility directives. The other two are
3461 This directive overrides the named symbols default visibility (which is set
3462 by their binding: local, global or weak). The directive sets the visibility
3465 which means that the symbols are considered to be
3467 (i.e., not visible to other components), and that some extra, processor specific
3468 processing must also be performed upon the symbols as well.
3470 .Ss Li .irp Va symbol, Va values...
3471 Evaluate a sequence of statements assigning different values to
3473 The sequence of statements starts at the
3475 directive, and is terminated by an
3482 and the sequence of statements is assembled. If no
3484 is listed, the sequence of statements is assembled once, with
3486 set to the null string. To refer to
3488 within the sequence of statements, use
3491 For example, assembling
3493 .Bd -literal -offset indent
3499 is equivalent to assembling
3501 .Bd -literal -offset indent
3507 For some caveats with the spelling of
3511 .Ss Li .irpc Va symbol, Va values...
3512 Evaluate a sequence of statements assigning different values to
3514 The sequence of statements starts at the
3516 directive, and is terminated by an
3518 directive. For each character in
3521 is set to the character, and the sequence of statements is assembled. If no
3523 is listed, the sequence of statements is assembled once, with
3525 set to the null string. To refer to
3527 within the sequence of statements, use
3530 For example, assembling
3532 .Bd -literal -offset indent
3538 is equivalent to assembling
3540 .Bd -literal -offset indent
3546 For some caveats with the spelling of
3548 see also the discussion atSee Section
3551 .Ss Li .lcomm Va symbol , Va length
3554 (an absolute expression) bytes for a local common denoted by
3556 The section and value of
3558 are those of the new local common. The addresses are allocated in the bss
3559 section, so that at run-time the bytes start off zeroed.
3561 is not declared global (see Section
3563 so is normally not visible to
3568 accepts this directive, for compatibility with other assemblers, but ignores
3571 .Ss Li .line Va line-number
3572 Even though this is a directive associated with the
3576 object-code formats,
3578 still recognizes it when producing COFF output, and treats
3580 as though it were the COFF
3583 it is found outside a
3592 is, instead, one of the directives used by compilers to generate auxiliary
3593 symbol information for debugging.
3595 .Ss Li .linkonce [ Va type]
3596 Mark the current section so that the linker only includes a single copy of
3597 it. This may be used to include the same section in several different object
3598 files, but ensure that the linker will only include it once in the final output
3601 pseudo-op must be used for each instance of the section. Duplicate sections
3602 are detected based on the section name, so it should be unique.
3604 This directive is only supported by a few object file formats; as of this
3605 writing, the only object file format which supports it is the Portable Executable
3606 format used on Windows NT.
3610 argument is optional. If specified, it must be one of the following strings.
3612 .Bd -literal -offset indent
3613 \&.linkonce same_size
3615 Not all types may be supported on all object file formats.
3619 Silently discard duplicate sections. This is the default.
3622 Warn if there are duplicate sections, but still keep only one copy.
3625 Warn if any of the duplicates have different sizes.
3628 Warn if any of the duplicates do not have exactly the same contents.
3631 .Ss Li .ln Va line-number
3639 is non-zero, this tells
3641 to enter MRI mode. If
3645 to exit MRI mode. This change affects code assembled until the next
3647 directive, or until the end of the file.See Section
3651 Control (in conjunction with the
3653 directive) whether or not assembly listings are generated. These two directives
3654 maintain an internal counter (which is zero initially).
3656 increments the counter, and
3658 decrements it. Assembly listings are generated whenever the counter is greater
3661 By default, listings are disabled. When you enable them (with the
3663 command line option;see Section
3665 the initial value of the listing counter is one.
3667 .Ss Li .long Va expressions
3671 See Section.Dq Int .
3678 allow you to define macros that generate assembly output. For example, this
3679 definition specifies a macro
3681 that puts a sequence of numbers into memory:
3683 .Bd -literal -offset indent
3684 .macro sum from=0, to=5
3687 sum "(\efrom+1)",\eto
3692 With that definition,
3694 is equivalent to this assembly input:
3696 .Bd -literal -offset indent
3706 .It .macro Va macname
3707 .It .macro Va macname Va macargs ...
3708 Begin the definition of a macro called
3710 If your macro definition requires arguments, specify their names after the
3711 macro name, separated by commas or spaces. You can qualify the macro argument
3712 to indicate whether all invocations must specify a non-blank value (through
3714 or whether it takes all of the remaining arguments (through
3716 You can supply a default value for any macro argument by following the name
3719 You cannot define two macros with the same
3721 unless it has been subject to the
3723 directive (see Section
3725 between the two definitions. For example, these are all valid
3731 Begin the definition of a macro called
3733 which takes no arguments.
3735 .It .macro plus1 p, p1
3736 .It .macro plus1 p p1
3737 Either statement begins the definition of a macro called
3739 which takes two arguments; within the macro definition, write
3743 to evaluate the arguments.
3745 .It .macro reserve_str p1=0 p2
3746 Begin the definition of a macro called
3748 with two arguments. The first argument has a default value, but not the second.
3749 After the definition is complete, you can call the macro either as
3750 .Li reserve_str Va a, Va b
3760 .Li reserve_str , Va b
3763 evaluating as the default, in this case
3770 .It .macro m p1:req, p2=0, p3:vararg
3771 Begin the definition of a macro called
3773 with at least three arguments. The first argument must always have a value
3774 specified, but not the second, which instead has a default value. The third
3775 formal will get assigned all remaining arguments specified at invocation time.
3777 When you call a macro, you can specify the argument values either by position,
3778 or by keyword. For example,
3781 .Li sum to=17, from=9 .
3784 Note that since each of the
3786 can be an identifier exactly as any other one permitted by the target architecture,
3787 there may be occasional problems if the target hand-crafts special meanings
3788 to certain characters when they occur in a special position. For example,
3791 is generally permitted to be part of a symbol name, but the architecture specific
3792 code special-cases it when occurring as the final character of a symbol (to
3793 denote a label), then the macro parameter replacement code will have no way
3794 of knowing that and consider the whole construct (including the colon) an
3795 identifier, and check only this identifier for being the subject to parameter
3796 substitution. So for example this macro definition:
3798 .Bd -literal -offset indent
3804 might not work as expected. Invoking
3806 might not create a label called
3808 but instead just insert the text
3810 into the assembler source, probably generating an error about an unrecognised
3813 Similarly problems might occur with the period character (
3815 which is often allowed inside opcode names (and hence identifier names). So
3816 for example constructing a macro to build an opcode from a base name and a
3817 length specifier like this:
3819 .Bd -literal -offset indent
3820 .macro opcode base length
3829 instruction but instead generate some kind of error as the assembler tries
3830 to interpret the text
3831 .Li \ebase.\elength .
3833 There are several possible ways around this problem:
3836 .It Insert white space
3837 If it is possible to use white space characters then this is the simplest
3840 .Bd -literal -offset indent
3849 can be used to separate the end of a macro argument from the following text.
3852 .Bd -literal -offset indent
3853 .macro opcode base length
3858 .It Use the alternate macro syntax mode
3859 In the alternative macro syntax mode the ampersand character (
3861 can be used as a separator. eg:
3863 .Bd -literal -offset indent
3871 Note: this problem of correctly identifying string parameters to pseudo ops
3872 also applies to the identifiers used in
3883 Mark the end of a macro definition.
3886 Exit early from the current macro definition.
3890 maintains a counter of how many macros it has executed in this pseudo-variable;
3891 you can copy that number to your output with
3894 .Em only within a macro definition .
3896 .It LOCAL Va name [ , ... ]
3897 .Em Warning: Li LOCAL is only available if you select \(lqalternate macro syntax\(rq with Li --alternate or Li .altmacro.
3898 See Section.Dq Altmacro .
3902 Enable alternate macro mode, enabling:
3905 .It LOCAL Va name [ , ... ]
3906 One additional directive,
3908 is available. It is used to generate a string replacement for each of the
3910 arguments, and replace any instances of
3912 in each macro expansion. The replacement string is unique in the assembly,
3913 and different for each separate macro expansion.
3915 allows you to write macros that define symbols, without fear of conflict between
3916 separate macro expansions.
3918 .It String delimiters
3919 You can write strings delimited in these other ways besides
3924 You can delimit strings with single-quote characters.
3927 You can delimit strings with matching angle brackets.
3930 .It single-character string escape
3931 To include any single character literally in a string (even if the character
3932 would otherwise have some special meaning), you can prefix the character with
3934 (an exclamation mark). For example, you can write
3936 to get the literal text
3939 .It Expression results as strings
3942 to evaluate the expression
3944 and use the result as a string.
3948 Disable alternate macro mode.See Section
3952 Control (in conjunction with the
3954 directive) whether or not assembly listings are generated. These two directives
3955 maintain an internal counter (which is zero initially).
3957 increments the counter, and
3959 decrements it. Assembly listings are generated whenever the counter is greater
3962 .Ss Li .octa Va biGNUms
3963 This directive expects zero or more biGNUms, separated by commas. For each
3964 biGNUm, it emits a 16-byte integer.
3966 The term \(lqocta\(rq comes from contexts in which a \(lqword\(rq is two bytes; hence
3970 .Ss Li .org Va new-lc , Va fill
3971 Advance the location counter of the current section to
3974 is either an absolute expression or an expression with the same section as
3975 the current subsection. That is, you can't use
3977 to cross sections: if
3979 has the wrong section, the
3981 directive is ignored. To be compatible with former assemblers, if the section
3986 issues a warning, then pretends the section of
3988 is the same as the current subsection.
3991 may only increase the location counter, or leave it unchanged; you cannot
3994 to move the location counter backwards.
3998 tries to assemble programs in one pass,
4000 may not be undefined. If you really detest this restriction we eagerly await
4001 a chance to share your improved assembler.
4003 Beware that the origin is relative to the start of the section, not to the
4004 start of the subsection. This is compatible with other people's assemblers.
4006 When the location counter (of the current subsection) is advanced, the intervening
4007 bytes are filled with
4009 which should be an absolute expression. If the comma and
4015 .Ss Li .p2align[wl] Va abs-expr, Va abs-expr, Va abs-expr
4016 Pad the location counter (in the current subsection) to a particular storage
4017 boundary. The first expression (which must be absolute) is the number of low-order
4018 zero bits the location counter must have after advancement. For example
4020 advances the location counter until it a multiple of 8. If the location counter
4021 is already a multiple of 8, no change is needed.
4023 The second expression (also absolute) gives the fill value to be stored in
4024 the padding bytes. It (and the comma) may be omitted. If it is omitted, the
4025 padding bytes are normally zero. However, on some systems, if the section
4026 is marked as containing code and the fill value is omitted, the space is filled
4027 with no-op instructions.
4029 The third expression is also absolute, and is also optional. If it is present,
4030 it is the maximum number of bytes that should be skipped by this alignment
4031 directive. If doing the alignment would require skipping more bytes than the
4032 specified maximum, then the alignment is not done at all. You can omit the
4033 fill value (the second argument) entirely by simply using two commas after
4034 the required alignment; this can be useful if you want the alignment to be
4035 filled with no-op instructions when appropriate.
4041 directives are variants of the
4045 directive treats the fill pattern as a two byte word value. The
4047 directives treats the fill pattern as a four byte longword value. For example,
4048 .Li .p2alignw 2,0x368d
4049 will align to a multiple of 4. If it skips two bytes, they will be filled
4050 in with the value 0x368d (the exact placement of the bytes depends upon the
4051 endianness of the processor). If it skips 1 or 3 bytes, the fill value is
4055 This is one of the ELF section stack manipulation directives. The others are
4070 This directive swaps the current section (and subsection) with most recently
4071 referenced section (and subsection) prior to this one. Multiple
4073 directives in a row will flip between two sections (and their subsections).
4075 In terms of the section stack, this directive swaps the current section with
4076 the top section on the section stack.
4079 This is one of the ELF section stack manipulation directives. The others are
4094 This directive replaces the current section (and subsection) with the top
4095 section (and subsection) on the section stack. This section is popped off
4098 .Ss Li .print Va string
4102 on the standard output during assembly. You must put
4106 .Ss Li .protected Va names
4107 This is one of the ELF visibility directives. The other two are
4116 This directive overrides the named symbols default visibility (which is set
4117 by their binding: local, global or weak). The directive sets the visibility
4120 which means that any references to the symbols from within the components
4121 that defines them must be resolved to the definition in that component, even
4122 if a definition in another component would normally preempt this.
4124 .Ss Li .psize Va lines , Va columns
4125 Use this directive to declare the number of lines---and, optionally, the number
4126 of columns---to use for each page, when generating listings.
4130 listings use a default line-count of 60. You may omit the comma and
4132 specification; the default width is 200 columns.
4135 generates formfeeds whenever the specified number of lines is exceeded (or
4136 whenever you explicitly request one, using
4143 no formfeeds are generated save those explicitly specified with
4146 .Ss Li .purgem Va name
4149 so that later uses of the string will not be expanded.See Section
4152 .Ss Li .pushsection Va name , Va subsection
4153 This is one of the ELF section stack manipulation directives. The others are
4168 This directive pushes the current section (and subsection) onto the top of
4169 the section stack, and then replaces the current section and subsection with
4174 .Ss Li .quad Va biGNUms
4176 expects zero or more biGNUms, separated by commas. For each bignum, it emits
4177 an 8-byte integer. If the biGNUm won't fit in 8 bytes, it prints a warning
4178 message; and just takes the lowest order 8 bytes of the biGNUm.
4180 The term \(lqquad\(rq comes from contexts in which a \(lqword\(rq is two bytes; hence
4184 .Ss Li .reloc Va offset, Va reloc_name[, Va expression]
4185 Generate a relocation at
4193 is a number, the relocation is generated in the current section. If
4195 is an expression that resolves to a symbol plus offset, the relocation is
4196 generated in the given symbol's section.
4198 if present, must resolve to a symbol plus addend or to an absolute value,
4199 but note that not all targets support an addend. e.g. ELF REL targets such
4200 as i386 store an addend in the section contents rather than in the relocation.
4201 This low level interface does not support addends stored in the section.
4203 .Ss Li .rept Va count
4204 Repeat the sequence of lines between the
4206 directive and the next
4212 For example, assembling
4214 .Bd -literal -offset indent
4220 is equivalent to assembling
4222 .Bd -literal -offset indent
4228 .Ss Li .sbttl " Va subheading"
4231 as the title (third line, immediately after the title line) when generating
4234 This directive affects subsequent pages, as well as the current page if it
4235 appears within ten lines of the top of a page.
4237 .Ss Li .section Va name
4240 directive to assemble the following code into a section named
4243 This directive is only supported for targets that actually support arbitrarily
4246 targets, for example, it is not accepted, even with a standard
4250 This is one of the ELF section stack manipulation directives. The others are
4265 For ELF targets, the
4267 directive is used like this:
4269 .Bd -literal -offset indent
4270 \&.section name [, "flags"[, @type[,flag_specific_arguments]]]
4275 argument is a quoted string which may contain any combination of the following
4279 section is allocatable
4283 section is executable
4285 section is mergeable
4287 section contains zero terminated strings
4289 section is a member of a section group
4291 section is used for thread-local-storage
4296 argument may contain one of the following constants:
4299 section contains data
4301 section does not contain data (i.e., section only occupies space)
4303 section contains data which is used by things other than the program
4305 section contains an array of pointers to init functions
4307 section contains an array of pointers to finish functions
4309 section contains an array of pointers to pre-init functions
4312 Many targets only support the first three section types.
4314 Note on targets where the
4316 character is the start of a comment (eg ARM) then another character is used
4317 instead. For example the ARM port uses the
4327 argument must be specified as well as an extra argument---
4331 .Bd -literal -offset indent
4332 \&.section name , "flags"M, @type, entsize
4339 flag must contain fixed size constants, each
4341 octets long. Sections with both
4345 must contain zero terminated strings where each character is
4347 bytes long. The linker may remove duplicates within sections with the same
4348 name, same entity size and same flags.
4350 must be an absolute expression.
4358 argument must be present along with an additional field like this:
4360 .Bd -literal -offset indent
4361 \&.section name , "flags"G, @type, GroupName[, linkage]
4366 field specifies the name of the section group to which this particular section
4367 belongs. The optional linkage field can contain:
4370 indicates that only one copy of this section should be retained
4379 flags are present then the fields for the Merge flag should come first, like
4382 .Bd -literal -offset indent
4383 \&.section name , "flags"MG, @type, entsize, GroupName[, linkage]
4386 If no flags are specified, the default flags depend upon the section name.
4387 If the section name is not recognized, the default will be for the section
4388 to have none of the above flags: it will not be allocated in memory, nor writable,
4389 nor executable. The section will contain data.
4391 For ELF targets, the assembler supports another type of
4393 directive for compatibility with the Solaris assembler:
4395 .Bd -literal -offset indent
4396 \&.section "name"[, flags...]
4399 Note that the section name is quoted. There may be a sequence of comma separated
4403 section is allocatable
4407 section is executable
4409 section is used for thread local storage
4412 This directive replaces the current section and subsection. See the contents
4413 of the gas testsuite directory
4414 .Li gas/testsuite/gas/elf
4415 for some examples of how this directive and the other section stack directives
4418 .Ss Li .set Va symbol, Va expression
4425 \&'s value and type to conform to
4429 was flagged as external, it remains flagged (see Section
4430 .Dq Symbol Attributes ) .
4434 a symbol many times in the same assembly.
4438 a global symbol, the value stored in the object file is the last value stored
4441 .Ss Li .short Va expressions
4442 This expects zero or more
4444 and emits a 16 bit number for each.
4446 .Ss Li .single Va flonums
4447 This directive assembles zero or more flonums, separated by commas. It has
4452 This directive is used to set the size associated with a symbol.
4454 For ELF targets, the
4456 directive is used like this:
4458 .Bd -literal -offset indent
4459 \&.size name , expression
4462 This directive sets the size associated with a symbol
4464 The size in bytes is computed from
4466 which can make use of label arithmetic. This directive is typically used to
4467 set the size of function symbols.
4469 .Ss Li .sleb128 Va expressions
4471 stands for \(lqsigned little endian base 128.\(rq This is a compact, variable length
4472 representation of numbers used by the DWARF symbolic debugging format.See Section
4475 .Ss Li .skip Va size , Va fill
4476 This directive emits
4478 bytes, each of value
4484 are absolute expressions. If the comma and
4488 is assumed to be zero. This is the same as
4491 .Ss Li .space Va size , Va fill
4492 This directive emits
4494 bytes, each of value
4500 are absolute expressions. If the comma and
4504 is assumed to be zero. This is the same as
4507 .Ss Li .stabd, .stabn, .stabs
4508 There are three directives that begin
4510 All emit symbols (see Section
4512 for use by symbolic debuggers. The symbols are not entered in the
4514 hash table: they cannot be referenced elsewhere in the source file. Up to
4515 five fields are required:
4519 This is the symbol's name. It may contain any character except
4521 so is more general than ordinary symbol names. Some debuggers used to code
4522 arbitrarily complex structures into symbol names using this field.
4525 An absolute expression. The symbol's type is set to the low 8 bits of this
4526 expression. Any bit pattern is permitted, but
4528 and debuggers choke on silly bit patterns.
4531 An absolute expression. The symbol's \(lqother\(rq attribute is set to the low 8 bits
4535 An absolute expression. The symbol's descriptor is set to the low 16 bits
4539 An absolute expression which becomes the symbol's value.
4542 If a warning is detected while reading a
4547 statement, the symbol has probably already been created; you get a half-formed
4548 symbol in your object file. This is compatible with earlier assemblers!
4551 .It .stabd Va type , Va other , Va desc
4553 The \(lqname\(rq of the symbol generated is not even an empty string. It is a null
4554 pointer, for compatibility. Older assemblers used a null pointer so they didn't
4555 waste space in object files with empty strings.
4557 The symbol's value is set to the location counter, relocatably. When your
4558 program is linked, the value of this symbol is the address of the location
4563 .It .stabn Va type , Va other , Va desc , Va value
4564 The name of the symbol is set to the empty string
4567 .It .stabs Va string , Va type , Va other , Va desc , Va value
4568 All five fields are specified.
4571 .Ss Li .string " Va str"
4572 Copy the characters in
4574 to the object file. You may specify more than one string to copy, separated
4575 by commas. Unless otherwise specified for a particular machine, the assembler
4576 marks the end of each string with a 0 byte. You can use any of the escape
4577 sequences described in Strings,,Strings.
4579 .Ss Li .struct Va expression
4580 Switch to the absolute section, and set the section offset to
4582 which must be an absolute expression. You might use this as follows:
4583 .Bd -literal -offset indent
4591 This would define the symbol
4593 to have the value 0, the symbol
4595 to have the value 4, and the symbol
4597 to have the value 8. Assembly would be left in the absolute section, and you
4600 directive of some sort to change to some other section before further assembly.
4602 .Ss Li .subsection Va name
4603 This is one of the ELF section stack manipulation directives. The others are
4618 This directive replaces the current subsection with
4620 The current section is not changed. The replaced subsection is put onto the
4621 section stack in place of the then current top of stack subsection.
4626 directive to bind symbols to specific version nodes within a source file.
4627 This is only supported on ELF platforms, and is typically used when assembling
4628 files to be linked into a shared library. There are cases where it may make
4629 sense to use this in objects to be bound into an application itself so as
4630 to override a versioned symbol from a shared library.
4632 For ELF targets, the
4634 directive can be used like this:
4635 .Bd -literal -offset indent
4636 \&.symver name, name2@nodename
4640 is defined within the file being assembled, the
4642 directive effectively creates a symbol alias with the name
4643 .Va name2@nodename ,
4644 and in fact the main reason that we just don't try and create a regular alias
4647 character isn't permitted in symbol names. The
4649 part of the name is the actual name of the symbol by which it will be externally
4650 referenced. The name
4652 itself is merely a name of convenience that is used so that it is possible
4653 to have definitions for multiple versions of a function within a single source
4654 file, and so that the compiler can unambiguously know which version of a function
4655 is being mentioned. The
4657 portion of the alias should be the name of a node specified in the version
4658 script supplied to the linker when building a shared library. If you are attempting
4659 to override a versioned symbol from a shared library, then
4661 should correspond to the nodename of the symbol you are trying to override.
4665 is not defined within the file being assembled, all references to
4668 .Va name2@nodename .
4673 will be removed from the symbol table.
4675 Another usage of the
4678 .Bd -literal -offset indent
4679 \&.symver name, name2@@nodename
4681 In this case, the symbol
4683 must exist and be defined within the file being assembled. It is similar to
4684 .Va name2@nodename .
4687 will also be used to resolve references to
4691 The third usage of the
4694 .Bd -literal -offset indent
4695 \&.symver name, name2@@@nodename
4699 is not defined within the file being assembled, it is treated as
4700 .Va name2@nodename .
4703 is defined within the file being assembled, the symbol name,
4706 .Va name2@@nodename .
4708 .Ss Li .text Va subsection
4711 to assemble the following statements onto the end of the text subsection numbered
4713 which is an absolute expression. If
4715 is omitted, subsection number zero is used.
4717 .Ss Li .title " Va heading"
4720 as the title (second line, immediately after the source file name and pagenumber)
4721 when generating assembly listings.
4723 This directive affects subsequent pages, as well as the current page if it
4724 appears within ten lines of the top of a page.
4727 This directive is used to set the type of a symbol.
4729 For ELF targets, the
4731 directive is used like this:
4733 .Bd -literal -offset indent
4734 \&.type name , type description
4737 This sets the type of symbol
4739 to be either a function symbol or an object symbol. There are five different
4740 syntaxes supported for the
4741 .Va type description
4742 field, in order to provide compatibility with various other assemblers.
4744 Because some of the characters used in these syntaxes (such as
4748 are comment characters for some architectures, some of the syntaxes below
4749 do not work on all architectures. The first variant will be accepted by the
4750 GNU assembler on all architectures so that variant should be used for maximum
4751 portability, if you do not need to assemble your code with other assemblers.
4753 The syntaxes supported are:
4755 .Bd -literal -offset indent
4756 .type <name> STT_FUNCTION
4757 .type <name> STT_OBJECT
4759 .type <name>,#function
4760 .type <name>,#object
4762 .type <name>,@function
4763 .type <name>,@object
4765 .type <name>,%function
4766 .type <name>,%object
4768 .type <name>,"function"
4769 .type <name>,"object"
4772 .Ss Li .uleb128 Va expressions
4774 stands for \(lqunsigned little endian base 128.\(rq This is a compact, variable length
4775 representation of numbers used by the DWARF symbolic debugging format.See Section
4778 .Ss Li .version " Va string"
4779 This directive creates a
4781 section and places into it an ELF formatted note of type NT_VERSION. The note's
4785 .Ss Li .vtable_entry Va table, Va offset
4786 This directive finds or creates a symbol
4790 relocation for it with an addend of
4793 .Ss Li .vtable_inherit Va child, Va parent
4794 This directive finds the symbol
4796 and finds or creates the symbol
4800 relocation for the parent whose addend is the value of the child symbol. As
4801 a special case the parent name of
4803 is treated as referring to the
4807 .Ss Li .warning " Va string"
4808 Similar to the directive
4812 but just emits a warning.
4814 .Ss Li .weak Va names
4815 This directive sets the weak attribute on the comma separated list of symbol
4817 If the symbols do not already exist, they will be created.
4819 On COFF targets other than PE, weak symbols are a GNU extension. This directive
4820 sets the weak attribute on the comma separated list of symbol
4822 If the symbols do not already exist, they will be created.
4824 On the PE target, weak symbols are supported natively as weak aliases. When
4825 a weak symbol is created that is not an alias, GAS creates an alternate symbol
4826 to hold the default value.
4828 .Ss Li .weakref Va alias, Va target
4829 This directive creates an alias to the target symbol that enables the symbol
4830 to be referenced with weak-symbol semantics, but without actually making it
4831 weak. If direct references or definitions of the symbol are present, then
4832 the symbol will not be weak, but if all references to it are through weak
4833 references, the symbol will be marked as weak in the symbol table.
4835 The effect is equivalent to moving all references to the alias to a separate
4836 assembly source file, renaming the alias to the symbol in it, declaring the
4837 symbol as weak there, and running a reloadable link to merge the object files
4838 resulting from the assembly of the new source file and the old source file
4839 that had the references to the alias removed.
4841 The alias itself never makes to the symbol table, and is entirely handled
4842 within the assembler.
4844 .Ss Li .word Va expressions
4845 This directive expects zero or more
4847 of any section, separated by commas. For each expression,
4849 emits a 32-bit number.
4851 .Ss Deprecated Directives
4852 One day these directives won't work. They are included for compatibility with
4859 .Sh ARM Dependent Features
4862 .It -mcpu= Va processor[+ Va extension...]
4863 This option specifies the target processor. The assembler will issue an error
4864 message if an attempt is made to assemble an instruction which will not execute
4865 on the target processor. The following processor names are recognized:
4939 (ARM920 with Cirrus Maverick coprocessor),
4941 (Intel XScale processor)
4943 (Intel(r) XScale processor with Wireless MMX(tm) technology coprocessor) and
4947 may be used to allow the assembler to accept instructions valid for any ARM
4950 In addition to the basic instruction set, the assembler can be told to accept
4951 various extension mnemonics that extend the processor using the co-processor
4952 instruction space. For example,
4953 .Li -mcpu=arm920+maverick
4954 is equivalent to specifying
4956 The following extensions are currently supported:
4962 .It -march= Va architecture[+ Va extension...]
4963 This option specifies the target architecture. The assembler will issue an
4964 error message if an attempt is made to assemble an instruction which will
4965 not execute on the target architecture. The following architecture names are
4998 are specified, the assembler will use the setting for
5001 The architecture option can be extended with the same instruction set extension
5006 .It -mfpu= Va floating-point-format
5008 This option specifies the floating point format to assemble for. The assembler
5009 will issue an error message if an attempt is made to assemble an instruction
5010 which will not execute on the target floating point unit. The following format
5011 options are recognized:
5033 In addition to determining which instructions are assembled, this option also
5034 affects the way in which the
5036 assembler directive behaves when assembling little-endian code.
5038 The default is dependent on the processor selected. For Architecture 5 or
5039 later, the default is to assembler for VFP instructions; for earlier architectures
5040 the default is to assemble for FPA instructions.
5043 This option specifies that the assembler should start assembling Thumb instructions;
5044 that is, it should behave as though the file starts with a
5048 .It -mthumb-interwork
5049 This option specifies that the output generated by the assembler should be
5050 marked as supporting interworking.
5052 .It -mapcs Li [26|32]
5053 This option specifies that the output generated by the assembler should be
5054 marked as supporting the indicated version of the Arm Procedure. Calling Standard.
5057 This option specifies that the output generated by the assembler should be
5058 marked as supporting the Arm/Thumb Procedure Calling Standard. If enabled
5059 this option will cause the assembler to create an empty debugging section
5060 in the object file called .arm.atpcs. Debuggers can use this to determine
5061 the ABI being used by.
5064 This indicates the floating point variant of the APCS should be used. In this
5065 variant floating point arguments are passed in FP registers rather than integer
5068 .It -mapcs-reentrant
5069 This indicates that the reentrant variant of the APCS should be used. This
5070 variant supports position independent code.
5072 .It -mfloat-abi= Va abi
5073 This option specifies that the output generated by the assembler should be
5074 marked as using specified floating point ABI. The following values are recognized:
5081 This option specifies which EABI version the produced object files should
5082 conform to. The following values are recognized:
5089 This option specifies that the output generated by the assembler should be
5090 marked as being encoded for a big-endian processor.
5093 This option specifies that the output generated by the assembler should be
5094 marked as being encoded for a little-endian processor.
5097 This option specifies that the output of the assembler should be marked as
5098 position-independent code (PIC).
5102 .Em Special Characters
5106 on a line indicates the start of a comment that extends to the end of the
5109 appears as the first character of a line, the whole line is treated as a comment.
5113 character can be used instead of a newline to separate statements.
5119 can be used to indicate immediate operands.
5121 *TODO* Explain about /data modifier on symbols.
5125 *TODO* Explain about ARM register naming, and the predefined names.
5127 .Em ARM relocation generation
5129 Specific data relocations can be generated by putting the relocation name
5130 in parentheses after the symbol name. For example:
5132 .Bd -literal -offset indent
5136 This will generate an
5138 relocation against the symbol
5140 The following relocations are supported:
5153 For compatibility with older toolchains the assembler also accepts
5155 after branch targets. This will generate the deprecated
5163 instructions can be generated by prefixing the value with
5167 respectively. For example to load the 32-bit address of foo into r0:
5169 .Bd -literal -offset indent
5170 MOVW r0, #:lower16:foo
5171 MOVT r0, #:upper16:foo
5175 The ARM family uses ieee floating-point numbers.
5177 .Ss ARM Machine Directives
5179 .It .align Va expression [, Va expression]
5182 directive. For the ARM however if the first argument is zero (ie no alignment
5183 is needed) the assembler will behave as if the argument had been 2 (ie pad
5184 to the next four byte boundary). This is for compatibility with ARM's own
5187 .It Va name .req Va register name
5188 This creates an alias for
5194 .Bd -literal -offset indent
5198 .It .unreq Va alias-name
5199 This undefines a register alias which was previously defined using the
5204 directives. For example:
5206 .Bd -literal -offset indent
5211 An error occurs if the name is undefined. Note - this pseudo op can be used
5212 to delete builtin in register name aliases (eg 'r0'). This should only be
5213 done if it is really necessary.
5215 .It Va name .dn Va register name [ Va .type] [ Va [index]]
5216 .It Va name .qn Va register name [ Va .type] [ Va [index]]
5222 directives are used to create typed and/or indexed register aliases for use
5223 in Advanced SIMD Extension (Neon) instructions. The former should be used
5224 to create aliases of double-precision registers, and the latter to create
5225 aliases of quad-precision registers.
5227 If these directives are used to create typed aliases, those aliases can be
5228 used in Neon instructions instead of writing types after the mnemonic or after
5229 each operand. For example:
5231 .Bd -literal -offset indent
5238 This is equivalent to writing the following:
5240 .Bd -literal -offset indent
5241 vmul.f32 d2,d3,d4[1]
5244 Aliases created using
5248 can be destroyed using
5251 .It .code Li [16|32]
5252 This directive selects the instruction set being generated. The value 16 selects
5253 Thumb, with the value 32 selecting ARM.
5256 This performs the same action as
5260 This performs the same action as
5264 This directive forces the selection of Thumb instructions, even if the target
5265 processor does not support those instructions
5268 This directive specifies that the following symbol is the name of a Thumb
5269 encoded function. This information is necessary in order to allow the assembler
5270 and linker to generate correct code for interworking between Arm and Thumb
5271 instructions and should be used even if interworking is not going to be performed.
5272 The presence of this directive also implies
5275 This directive is not neccessary when generating EABI objects. On these targets
5276 the encoding is implicit when generating Thumb code.
5279 This performs the equivalent of a
5281 directive in that it creates a symbol which is an alias for another symbol
5282 (possibly not yet defined). This directive also has the added property in
5283 that it marks the aliased symbol as being a thumb function entry point, in
5284 the same way that the
5289 This directive causes the current contents of the literal pool to be dumped
5290 into the current section (which is assumed to be the .text section) at the
5291 current location (aligned to a word boundary).
5293 maintains a separate literal pool for each section and each sub-section. The
5295 directive will only affect the literal pool of the current section and sub-section.
5296 At the end of assembly all remaining, un-empty literal pools will automatically
5299 Note - older versions of
5301 would dump the current literal pool any time a section change occurred. This
5302 is no longer done, since it prevents accurate control of the placement of
5306 This is a synonym for .ltorg.
5309 Marks the start of a function with an unwind table entry.
5312 Marks the end of a function with an unwind table entry. The unwind index table
5313 entry is created when this directive is processed.
5315 If no personality routine has been specified then standard personality routine
5316 0 or 1 will be used, depending on the number of unwind opcodes required.
5319 Prevents unwinding through the current function. No personality routine or
5320 exception table data is required or permitted.
5322 .It .personality Va name
5323 Sets the personality routine for the current function to
5326 .It .personalityindex Va index
5327 Sets the personality routine for the current function to the EABI standard
5332 Marks the end of the current function, and the start of the exception table
5333 entry for that function. Anything between this directive and the
5335 directive will be added to the exception table entry.
5337 Must be preceded by a
5340 .Li .personalityindex
5343 .It .save Va reglist
5344 Generate unwinder annotations to restore the registers in
5348 is the same as the corresponding store-multiple instruction.
5350 .Bd -literal -offset indent
5351 .save {r4, r5, r6, lr}
5352 stmfd sp!, {r4, r5, r6, lr}
5356 fstmdx sp!, {d8, d9, d10}
5358 wstrd wr11, [sp, #-8]!
5359 wstrd wr10, [sp, #-8]!
5362 wstrd wr11, [sp, #-8]!
5364 wstrd wr10, [sp, #-8]!
5367 .It .vsave Va vfp-reglist
5368 Generate unwinder annotations to restore the VFP registers in
5370 using FLDMD. Also works for VFPv3 registers that are to be restored using
5373 is the same as the corresponding store-multiple instruction.
5375 .Bd -literal -offset indent
5376 .vsave {d8, d9, d10}
5377 fstmdd sp!, {d8, d9, d10}
5378 .vsave {d15, d16, d17}
5379 vstm sp!, {d15, d16, d17}
5382 Since FLDMX and FSTMX are now deprecated, this directive should be used in
5385 for saving VFP registers for ARMv6 and above.
5388 Generate unwinder annotations for a stack adjustment of
5390 bytes. A positive value indicates the function prologue allocated stack space
5391 by decrementing the stack pointer.
5393 .It .movsp Va reg [, # Va offset]
5394 Tell the unwinder that
5396 contains an offset from the current stack pointer. If
5398 is not specified then it is assumed to be zero.
5400 .It .setfp Va fpreg, Va spreg [, # Va offset]
5401 Make all unwinder annotations relaive to a frame pointer. Without this the
5402 unwinder will use offsets from the stack pointer.
5404 The syntax of this directive is the same as the
5408 instruction used to set the frame pointer.
5412 or mentioned in a previous
5416 .Bd -literal -offset indent
5424 .It .raw Va offset, Va byte1, ...
5425 Insert one of more arbitary unwind opcode bytes, which are known to adjust
5426 the stack pointer by
5431 .Li .unwind_raw 4, 0xb1, 0x01
5436 Select the target processor. Valid values for
5438 are the same as for the
5443 Select the target architecture. Valid values for
5445 are the same as for the
5449 .It .object_arch Va name
5450 Override the architecture recorded in the EABI object attribute section. Valid
5453 are the same as for the
5455 directive. Typically this is useful when code uses runtime detection of CPU
5459 Select the floating point unit to assemble for. Valid values for
5461 are the same as for the
5465 .It .eabi_attribute Va tag, Va value
5466 Set the EABI object attribute number
5470 The value is either a
5474 .Li number, "string"
5475 depending on the tag.
5480 implements all the standard ARM opcodes. It also implements several pseudo
5481 opcodes, including several synthetic load instructions.
5485 .Bd -literal -offset indent
5489 This pseudo op will always evaluate to a legal ARM instruction that does nothing.
5490 Currently it will evaluate to MOV r0, r0.
5493 .Bd -literal -offset indent
5494 ldr <register> , = <expression>
5497 If expression evaluates to a numeric constant then a MOV or MVN instruction
5498 will be used in place of the LDR instruction, if the constant can be generated
5499 by either of these instructions. Otherwise the constant will be placed into
5500 the nearest literal pool (if it not already there) and a PC relative LDR instruction
5504 .Bd -literal -offset indent
5505 adr <register> <label>
5508 This instruction will load the address of
5510 into the indicated register. The instruction will evaluate to a PC relative
5511 ADD or SUB instruction depending upon where the label is located. If the label
5512 is out of range, or if it is not defined in the same file (and section) as
5513 the ADR instruction, then an error will be generated. This instruction will
5514 not make use of the literal pool.
5517 .Bd -literal -offset indent
5518 adrl <register> <label>
5521 This instruction will load the address of
5523 into the indicated register. The instruction will evaluate to one or two PC
5524 relative ADD or SUB instructions depending upon where the label is located.
5525 If a second instruction is not needed a NOP instruction will be generated
5526 in its place, so that this instruction is always 8 bytes long.
5528 If the label is out of range, or if it is not defined in the same file (and
5529 section) as the ADRL instruction, then an error will be generated. This instruction
5530 will not make use of the literal pool.
5533 For information on the ARM or Thumb instruction sets, see
5534 .Em ARM Software Development Toolkit Reference Manual ,
5535 Advanced RISC Machines Ltd.
5538 The ARM ELF specification requires that special symbols be inserted into object
5539 files to mark certain features:
5543 At the start of a region of code containing ARM instructions.
5546 At the start of a region of code containing THUMB instructions.
5549 At the start of a region of data.
5552 The assembler will automatically insert these symbols for you - there is no
5553 need to code them yourself. Support for tagging symbols ($b, $f, $p and $m)
5554 which is also mentioned in the current ARM ELF specification is not implemented.
5555 This is because they have been dropped from the new EABI and so tools cannot
5556 rely upon their presence.
5558 .Sh 80386 Dependent Features
5561 supports both the original Intel 386 architecture in both 16 and 32-bit mode
5562 as well as AMD x86-64 architecture extending the Intel architecture to 64-bits.
5567 has a few machine dependent options:
5571 Select the word size, either 32 bits or 64 bits. Selecting 32-bit implies
5572 Intel i386 architecture, while 64-bit implies AMD x86-64 architecture.
5574 These options are only available with the ELF object file format, and require
5575 that the necessary BFD support has been included (on a 32-bit platform you
5576 have to add --enable-64-bit-bfd to configure enable 64-bit usage and use x86-64
5577 as target platform).
5580 By default, x86 GAS replaces multiple nop instructions used for alignment
5581 within code sections with multi-byte nop instructions such as leal 0(%esi,1),%esi.
5582 This switch disables the optimization.
5585 On SVR4-derived platforms, the character
5587 is treated as a comment character, which means that it cannot be used in expressions.
5592 into a normal character. This does not disable
5594 at the beginning of a line starting a comment, or affect using
5596 for starting a comment.
5599 This option specifies an instruction set architecture for generating instructions.
5600 The following architectures are recognized:
5627 This option only affects instructions generated by the assembler. The
5629 directive will take precedent.
5632 This option specifies a processor to optimize for. When used in conjunction
5635 option, only instructions of the processor specified by the
5637 option will be generated.
5641 values are identical to
5642 .Op -march= Va CPU .
5645 .Ss AT&T Syntax versus Intel Syntax
5647 now supports assembly using Intel assembler syntax.
5649 selects Intel mode, and
5651 switches back to the usual AT&T mode for compatibility with the output of
5653 Either of these directives may have an optional argument,
5657 specifying whether registers require a
5659 prefix. AT&T System V/386 assembler syntax is quite different from Intel syntax.
5660 We mention these differences because almost all 80386 documents use Intel
5661 syntax. Notable differences between the two syntaxes are:
5665 AT&T immediate operands are preceded by
5667 Intel immediate operands are undelimited (Intel
5671 AT&T register operands are preceded by
5673 Intel register operands are undelimited. AT&T absolute (as opposed to PC relative)
5674 jump/call operands are prefixed by
5676 they are undelimited in Intel syntax.
5679 AT&T and Intel syntax use the opposite order for source and destination operands.
5686 convention is maintained for compatibility with previous Unix assemblers.
5687 Note that instructions with more than one source operand, such as the
5691 have reversed order. i386-Bugs.
5694 In AT&T syntax the size of memory operands is determined from the last character
5695 of the instruction mnemonic. Mnemonic suffixes of
5701 specify byte (8-bit), word (16-bit), long (32-bit) and quadruple word (64-bit)
5702 memory references. Intel syntax accomplishes this by prefixing memory operands
5705 the instruction mnemonics) with
5712 .Li mov al, byte ptr Va foo
5714 .Li movb Va foo, %al
5718 Immediate form long jumps and calls are
5719 .Li lcall/ljmp $ Va section, $ Va offset
5720 in AT&T syntax; the Intel syntax is
5721 .Li call/jmp far Va section: Va offset .
5722 Also, the far return instruction is
5723 .Li lret $ Va stack-adjust
5724 in AT&T syntax; Intel syntax is
5725 .Li ret far Va stack-adjust .
5728 The AT&T assembler does not provide support for multiple section programs.
5729 Unix style systems expect all programs to be single sections.
5732 .Ss Instruction Naming
5733 Instruction mnemonics are suffixed with one character modifiers which specify
5734 the size of operands. The letters
5740 specify byte, word, long and quadruple word operands. If no suffix is specified
5741 by an instruction then
5743 tries to fill in the missing suffix based on the destination register operand
5744 (the last one by convention). Thus,
5752 Note that this is incompatible with the AT&T Unix assembler which assumes
5753 that a missing mnemonic suffix implies long operand size. (This incompatibility
5754 does not affect compiler output since compilers always explicitly specify
5755 the mnemonic suffix.)
5757 Almost all instructions have the same names in AT&T and Intel format. There
5758 are a few exceptions. The sign extend and zero extend instructions need two
5759 sizes to specify them. They need a size to sign/zero extend
5761 and a size to zero extend
5763 This is accomplished by using two instruction mnemonic suffixes in AT&T syntax.
5764 Base names for sign extend and zero extend are
5772 in Intel syntax). The instruction mnemonic suffixes are tacked on to this
5778 .Li movsbl %al, %edx
5779 is AT&T syntax for \(lqmove sign extend
5783 %edx.\(rq Possible suffixes, thus, are
5785 (from byte to long),
5787 (from byte to word),
5789 (from word to long),
5791 (from byte to quadruple word),
5793 (from word to quadruple word), and
5795 (from long to quadruple word).
5797 The Intel-syntax conversion instructions
5802 --- sign-extend byte in
5809 --- sign-extend word in
5816 --- sign-extend word in
5823 --- sign-extend dword in
5830 --- sign-extend dword in
5838 --- sign-extend quad in
5855 accepts either naming for these instructions.
5857 Far call/jump instructions are
5861 in AT&T syntax, but are
5865 in Intel convention.
5868 Register operands are always prefixed with
5870 The 80386 registers consist of
5874 the 8 32-bit registers
5883 (the frame pointer), and
5885 (the stack pointer).
5888 the 8 16-bit low-ends of these:
5900 the 8 8-bit registers:
5910 (These are the high-bytes and low-bytes of
5918 the 6 section registers
5931 the 3 processor control registers
5938 the 6 debug registers
5948 the 2 test registers
5954 the 8 floating point register stack
5966 These registers are overloaded by 8 MMX registers
5978 the 8 SSE registers registers
5990 The AMD x86-64 architecture extends the register set by:
5994 enhancing the 8 32-bit registers to 64-bit:
6003 (the frame pointer),
6008 the 8 extended registers
6014 the 8 32-bit low ends of the extended registers:
6020 the 8 16-bit low ends of the extended registers:
6026 the 8 8-bit low ends of the extended registers:
6032 the 4 8-bit registers:
6039 the 8 debug registers:
6045 the 8 SSE registers:
6051 .Ss Instruction Prefixes
6052 Instruction prefixes are used to modify the following instruction. They are
6053 used to repeat string instructions, to provide section overrides, to perform
6054 bus lock operations, and to change operand and address sizes. (Most instructions
6055 that normally operate on 32-bit operands will use 16-bit operands if the instruction
6056 has an \(lqoperand size\(rq prefix.) Instruction prefixes are best written on the
6057 same line as the instruction they act upon. For example, the
6059 (scan string) instruction is repeated with:
6061 .Bd -literal -offset indent
6062 repne scas %es:(%edi),%al
6065 You may also place prefixes on the lines immediately preceding the instruction,
6066 but this circumvents checks that
6068 does with prefixes, and will not work with all prefixes.
6070 Here is a list of instruction prefixes:
6074 Section override prefixes
6081 These are automatically added by specifying using the
6085 form for memory references.
6088 Operand/Address size prefixes
6092 change 32-bit operands/addresses into 16-bit operands/addresses, while
6096 change 16-bit ones (in a
6098 section) into 32-bit operands/addresses. These prefixes
6100 appear on the same line of code as the instruction they modify. For example,
6103 section, you might write:
6105 .Bd -literal -offset indent
6112 inhibits interrupts during execution of the instruction it precedes. (This
6113 is only valid with certain instructions; see a 80386 manual for details).
6116 The wait for coprocessor prefix
6118 waits for the coprocessor to complete the current instruction. This should
6119 never be needed for the 80386/80387 combination.
6127 prefixes are added to string instructions to make them repeat
6131 times if the current address size is 16-bits).
6135 family of prefixes is used by x86-64 to encode extensions to i386 instruction
6138 prefix has four bits --- an operand size overwrite (
6140 used to change operand size from 32-bit to 64-bit and X, Y and Z extensions
6141 bits used to extend the register set.
6145 prefixes directly. The
6149 prefix with all the bits set. By omitting the
6155 you may write other prefixes as well. Normally, there is no need to write
6156 the prefixes explicitly, since gas will automatically generate them based
6157 on the instruction operands.
6160 .Ss Memory References
6161 An Intel syntax indirect memory reference of the form
6163 .Bd -literal -offset indent
6164 section:[base + index*scale + disp]
6167 is translated into the AT&T syntax
6169 .Bd -literal -offset indent
6170 section:disp(base, index, scale)
6177 are the optional 32-bit base and index registers,
6179 is the optional displacement, and
6181 taking the values 1, 2, 4, and 8, multiplies
6183 to calculate the address of the operand. If no
6189 specifies the optional section register for the memory operand, and may override
6190 the default section register (see a 80386 manual for section register defaults).
6191 Note that section overrides in AT&T syntax
6195 If you specify a section override which coincides with the default section
6200 output any section register override prefixes to assemble the given instruction.
6201 Thus, section overrides can be specified to emphasize which section register
6202 is used for a given memory operand.
6204 Here are some examples of Intel and AT&T style memory references:
6207 .It AT&T: Li -4(%ebp), Intel: Li [ebp - 4]
6215 is missing, and the default section is used (
6219 as the base register).
6224 .It AT&T: Li foo(,%eax,4), Intel: Li [foo + eax*4]
6234 All other fields are missing. The section register here defaults to
6237 .It AT&T: Li foo(,1); Intel Li [foo]
6238 This uses the value pointed to by
6240 as a memory operand. Note that
6244 are both missing, but there is only
6247 This is a syntactic exception.
6249 .It AT&T: Li %gs:foo; Intel Li gs:foo
6250 This selects the contents of the variable
6252 with section register
6258 Absolute (as opposed to PC relative) call and jump operands must be prefixed
6265 always chooses PC relative addressing for jump/call labels.
6267 Any instruction that has a memory operand, but no register operand,
6269 specify its size (byte, word, long, or quadruple) with an instruction mnemonic
6278 The x86-64 architecture adds an RIP (instruction pointer relative) addressing.
6279 This addressing mode is specified by using
6281 as a base register. Only constant offsets are valid. For example:
6284 .It AT&T: Li 1234(%rip), Intel: Li [rip + 1234]
6285 Points to the address 1234 bytes past the end of the current instruction.
6287 .It AT&T: Li symbol(%rip), Intel: Li [rip + symbol]
6290 in RIP relative way, this is shorter than the default absolute addressing.
6293 Other addressing modes remain unchanged in x86-64 architecture, except registers
6294 used are 64-bit instead of 32-bit.
6296 .Ss Handling of Jump Instructions
6297 Jump instructions are always optimized to use the smallest possible displacements.
6298 This is accomplished by using byte (8-bit) displacement jumps whenever the
6299 target is sufficiently close. If a byte displacement is insufficient a long
6300 displacement is used. We do not support word (16-bit) displacement jumps in
6301 32-bit mode (i.e. prefixing the jump instruction with the
6303 instruction prefix), since the 80386 insists upon masking
6305 to 16 bits after the word displacement is added. (See alsosee Section
6317 instructions only come in byte displacements, so that if you use these instructions
6320 does not use them) you may get an error message (and incorrect code). The
6321 AT&T 80386 assembler tries to get around this problem by expanding
6325 .Bd -literal -offset indent
6333 All 80387 floating point types except packed BCD are supported. (BCD support
6334 may be added without much difficulty). These data types are 16-, 32-, and
6335 64- bit integers, and single (32-bit), double (64-bit), and extended (80-bit)
6336 precision floating point. Each supported type has an instruction mnemonic
6337 suffix and a constructor associated with it. Instruction mnemonic suffixes
6338 specify the operand's data type. Constructors build these data types into
6343 Floating point constructors are
6350 for 32-, 64-, and 80-bit formats. These correspond to instruction mnemonic
6357 stands for 80-bit (ten byte) real. The 80387 only supports this format via
6360 (load 80-bit real to stack top) and
6362 (store 80-bit real and pop stack) instructions.
6365 Integer constructors are
6372 for the 16-, 32-, and 64-bit integer formats. The corresponding instruction
6373 mnemonic suffixes are
6379 (quad). As with the 80-bit real format, the 64-bit
6381 format is only present in the
6383 (load quad integer to stack top) and
6385 (store quad integer and pop stack) instructions.
6388 Register to register operations should not use instruction mnemonic suffixes.
6389 .Li fstl %st, %st(1)
6390 will give a warning, and be assembled as if you wrote
6391 .Li fst %st, %st(1) ,
6392 since all register to register operations use 80-bit floating point operands.
6397 from 80-bit to 64-bit floating point format, then stores the result in the
6401 .Ss Intel's MMX and AMD's 3DNow! SIMD Operations
6403 supports Intel's MMX instruction set (SIMD instructions for integer data),
6404 available on Intel's Pentium MMX processors and Pentium II processors, AMD's
6405 K6 and K6-2 processors, Cyrix' M2 processor, and probably others. It also
6406 supports AMD's 3DNow! instruction set (SIMD instructions for 32-bit floating
6407 point data) available on AMD's K6-2 processor and possibly others in the future.
6411 does not support Intel's floating point SIMD, Katmai (KNI).
6413 The eight 64-bit MMX operands, also used by 3DNow!, are called
6418 They contain eight 8-bit integers, four 16-bit integers, two 32-bit integers,
6419 one 64-bit integer, or two 32-bit floating point values. The MMX registers
6420 cannot be used at the same time as the floating point stack.
6422 See Intel and AMD documentation, keeping in mind that the operand order in
6423 instructions is reversed from the Intel syntax.
6425 .Ss Writing 16-bit Code
6428 normally writes only \(lqpure\(rq 32-bit i386 code or 64-bit x86-64 code depending
6429 on the default configuration, it also supports writing code to run in real
6430 mode or in 16-bit protected mode code segments. To do this, put a
6434 directive before the assembly language instructions to be run in 16-bit mode.
6437 back to writing normal 32-bit code with the
6442 provides experimental support for generating 16-bit code from gcc, and differs
6457 instructions default to 32-bit size. This is so that the stack pointer is
6458 manipulated in the same way over function calls, allowing access to function
6459 parameters at the same stack offsets as in 32-bit mode.
6461 also automatically adds address size prefixes where necessary to use the 32-bit
6462 addressing modes that gcc generates.
6466 generates in 16-bit mode will not necessarily run on a 16-bit pre-80386 processor.
6467 To write code that runs on such a processor, you must refrain from using
6469 32-bit constructs which require
6471 to output address or operand size prefixes.
6473 Note that writing 16-bit code instructions by explicitly specifying a prefix
6474 or an instruction mnemonic suffix within a 32-bit code section generates different
6475 machine instructions than those generated for a 16-bit code segment. In a
6476 32-bit code section, the following code generates the machine opcode bytes
6478 which pushes the value
6480 onto the stack, decrementing
6484 .Bd -literal -offset indent
6488 The same code in a 16-bit code section would generate the machine opcode bytes
6490 (i.e., without the operand size prefix), which is correct since the processor
6491 default operand size is assumed to be 16 bits in a 16-bit code section.
6493 .Ss AT&T Syntax bugs
6494 The UnixWare assembler, and probably other AT&T derived ix86 Unix assemblers,
6495 generate floating point instructions with reversed source and destination
6496 registers in certain cases. Unfortunately, gcc and possibly many other programs
6497 use this reversed syntax, so we're stuck with it.
6501 .Bd -literal -offset indent
6508 rather than the expected
6510 This happens with all the non-commutative arithmetic floating point operations
6511 with two register operands where the source register is
6513 and the destination register is
6516 .Ss Specifying CPU Architecture
6518 may be told to assemble for a particular CPU (sub-)architecture with the
6519 .Li .arch Va cpu_type
6520 directive. This directive enables a warning when gas detects an instruction
6521 that is not supported on the CPU specified. The choices for
6528 i8086 i186 i286 i386
6529 i486 i586 i686 pentium
6530 pentiumpro pentiumii pentiumiii pentium4
6531 prescott nocona core core2
6533 k6 athlon sledgehammer k8
6534 \&.mmx .sse .sse2 .sse3
6535 \&.ssse3 .sse4.1 .sse4.2 .sse4
6536 \&.sse4a .3dnow .3dnowa .padlock
6537 \&.pacifica .svme .abm
6540 Apart from the warning, there are only two other effects on
6542 operation; Firstly, if you specify a CPU other than
6544 then shift by one instructions such as
6546 will automatically use a two byte opcode sequence. The larger three byte opcode
6547 sequence is used on the 486 (and when no architecture is specified) because
6548 it executes faster on the 486. Note that you can explicitly request the two
6549 byte opcode by writing
6551 Secondly, if you specify
6560 then byte offset conditional jumps will be promoted when necessary to a two
6561 instruction sequence consisting of a conditional jump of the opposite sense
6562 around an unconditional jump to the target.
6564 Following the CPU architecture (but not a sub-architecture, which are those
6565 starting with a dot), you may specify
6569 to control automatic promotion of conditional jumps.
6571 is the default, and enables jump promotion; All external jumps will be of
6572 the long variety, and file-local jumps will be promoted as necessary. (see Section
6575 leaves external conditional jumps as byte offset jumps, and warns about file-local
6576 conditional jumps that
6578 promotes. Unconditional jumps are treated as for
6583 .Bd -literal -offset indent
6588 There is some trickery concerning the
6592 instructions that deserves mention. The 16-, 32-, 64- and 128-bit expanding
6593 multiplies (base opcode
6599 can be output only in the one operand form. Thus,
6603 select the expanding multiply; the expanding multiply would clobber the
6605 register, and this would confuse
6609 to get the 64-bit product in
6612 We have added a two operand form of
6614 when the first operand is an immediate mode expression and the second operand
6615 is a register. This is just a shorthand, so that, multiplying
6617 by 69, for example, can be done with
6620 .Li imul $69, %eax, %eax .
6622 .Sh IA-64 Dependent Features
6626 This option instructs the assembler to mark the resulting object file as using
6627 the \(lqconstant GP\(rq model. With this model, it is assumed that the entire program
6628 uses a single global pointer (GP) value. Note that this option does not in
6629 any fashion affect the machine code emitted by the assembler. All it does
6630 is turn on the EF_IA_64_CONS_GP flag in the ELF file header.
6633 This option instructs the assembler to mark the resulting object file as using
6634 the \(lqconstant GP without function descriptor\(rq data model. This model is like
6635 the \(lqconstant GP\(rq model, except that it additionally does away with function
6636 descriptors. What this means is that the address of a function refers directly
6637 to the function's code entry-point. Normally, such an address would refer
6638 to a function descriptor, which contains both the code entry-point and the
6639 GP-value needed by the function. Note that this option does not in any fashion
6640 affect the machine code emitted by the assembler. All it does is turn on the
6641 EF_IA_64_NOFUNCDESC_CONS_GP flag in the ELF file header.
6647 These options select the data model. The assembler defaults to
6653 These options select the byte order. The
6655 option selects little-endian byte order (default) and
6657 selects big-endian byte order. Note that IA-64 machine code always uses little-endian
6662 Tune for a particular IA-64 CPU,
6669 .It -munwind-check=warning
6670 .It -munwind-check=error
6671 These options control what the assembler will do when performing consistency
6672 checks on unwind directives.
6673 .Li -munwind-check=warning
6674 will make the assembler issue a warning when an unwind directive check fails.
6675 This is the default.
6676 .Li -munwind-check=error
6677 will make the assembler issue an error when an unwind directive check fails.
6680 .It -mhint.b=warning
6682 These options control what the assembler will do when the
6684 instruction is used.
6686 will make the assembler accept
6689 will make the assembler issue a warning when
6693 will make the assembler treat
6695 as an error, which is the default.
6699 These options turn on dependency violation checking.
6702 This option instructs the assembler to automatically insert stop bits where
6703 necessary to remove dependency violations. This is the default mode.
6706 This option turns off dependency violation checking.
6709 This turns on debug output intended to help tracking down bugs in the dependency
6713 This is a shortcut for -xnone -xdebug.
6716 This is a shortcut for -xexplicit -xdebug.
6720 The assembler syntax closely follows the IA-64 Assembly Language Reference
6723 .Em Special Characters
6726 is the line comment token.
6729 can be used instead of a newline to separate statements.
6733 The 128 integer registers are referred to as
6735 The 128 floating-point registers are referred to as
6737 The 128 application registers are referred to as
6739 The 128 control registers are referred to as
6741 The 64 one-bit predicate registers are referred to as
6743 The 8 branch registers are referred to as
6745 In addition, the assembler defines a number of aliases:
6775 For convenience, the assembler also defines aliases for all named application
6776 and control registers. For example,
6778 refers to the register backing store pointer (
6782 refers to the end-of-interrupt register (
6785 .Em IA-64 Processor-Status-Register (PSR) Bit Names
6787 The assembler defines bit masks for each of the bits in the IA-64 processor
6788 status register. For example,
6790 corresponds to a value of 0x2000. These masks are primarily intended for use
6799 instructions, but they can be used anywhere else where an integer constant
6803 For detailed information on the IA-64 machine instruction set, see the
6804 .Lk http://developer.intel.com/design/itanium/arch_spec.htm .
6806 .Sh MIPS Dependent Features
6809 for mips architectures supports several different mips processors, and MIPS
6810 ISA levels I through V, MIPS32, and MIPS64. For information about the mips
6811 instruction set, see
6812 .Em MIPS RISC Architecture ,
6813 by Kane and Heindrich (Prentice-Hall). For an overview of mips assembly conventions,
6814 see \(lqAppendix D: Assembly Language Programming\(rq in the same work.
6816 .Ss Assembler options
6817 The mips configurations of GNU
6819 support these special options:
6823 This option sets the largest size of an object that can be referenced implicitly
6826 register. It is only accepted for targets that use ecoff format. The default
6831 Any mips configuration of
6833 can select big-endian or little-endian output at run time (unlike the other
6834 GNU development tools, which must be configured for one or the other). Use
6836 to select big-endian output, and
6841 Generate SVR4-style PIC. This option tells the assembler to generate SVR4-style
6842 position-independent macro expansions. It also tells the assembler to mark
6843 the output file as PIC.
6846 Generate VxWorks PIC. This option tells the assembler to generate VxWorks-style
6847 position-independent macro expansions.
6858 Generate code for a particular MIPS Instruction Set Architecture level.
6860 corresponds to the r2000 and r3000 processors,
6862 to the r6000 processor,
6864 to the r4000 processor, and
6866 to the r8000 and r10000 processors.
6873 correspond to generic MIPS V, MIPS32, MIPS32 Release 2, MIPS64, and MIPS64
6874 Release 2 ISA processors, respectively. You can also switch instruction sets
6875 during the assembly; see MIPS ISA, Directives to override the ISA level.
6879 Some macros have different expansions for 32-bit and 64-bit registers. The
6880 register sizes are normally inferred from the ISA and ABI, but these flags
6881 force a certain group of registers to be treated as 32 bits wide at all times.
6883 controls the size of general-purpose registers and
6885 controls the size of floating-point registers.
6891 directives allow the size of registers to be changed for parts of an object.
6892 The default value is restored by
6895 .Li .set fp=default .
6897 On some MIPS variants there is a 32-bit mode flag; when this flag is set,
6898 64-bit instructions generate a trap. Also, some 32-bit OSes only save the
6899 32-bit registers on a context switch, so it is essential never to use the
6904 Assume that 64-bit registers are available. This is provided in the interests
6914 directives allow the size of registers to be changed for parts of an object.
6915 The default value is restored by
6918 .Li .set fp=default .
6922 Generate code for the MIPS 16 processor. This is equivalent to putting
6924 at the start of the assembly file.
6926 turns off this option.
6930 Enables the SmartMIPS extensions to the MIPS32 instruction set, which provides
6931 a number of new instructions which target smartcard and cryptographic applications.
6932 This is equivalent to putting
6934 at the start of the assembly file.
6936 turns off this option.
6940 Generate code for the MIPS-3D Application Specific Extension. This tells the
6941 assembler to accept MIPS-3D instructions.
6943 turns off this option.
6947 Generate code for the MDMX Application Specific Extension. This tells the
6948 assembler to accept MDMX instructions.
6950 turns off this option.
6954 Generate code for the DSP Release 1 Application Specific Extension. This tells
6955 the assembler to accept DSP Release 1 instructions.
6957 turns off this option.
6961 Generate code for the DSP Release 2 Application Specific Extension. This option
6962 implies -mdsp. This tells the assembler to accept DSP Release 2 instructions.
6964 turns off this option.
6968 Generate code for the MT Application Specific Extension. This tells the assembler
6969 to accept MT instructions.
6971 turns off this option.
6975 Cause nops to be inserted if the read of the destination register of an mfhi
6976 or mflo instruction occurs in the following two instructions.
6980 Insert nops to work around certain VR4120 errata. This option is intended
6981 to be used on GCC-generated code: it is not designed to catch all problems
6982 in hand-written assembler code.
6986 Insert nops to work around the VR4130
6994 Generate code for the LSI r4010 chip. This tells the assembler to accept the
6995 r4010 specific instructions (
6998 etc.), and to not schedule
7000 instructions around accesses to the
7006 turns off this option.
7010 Generate code for the MIPS r4650 chip. This tells the assembler to accept
7015 instruction, and to not schedule
7017 instructions around accesses to the
7023 turns off this option.
7031 generate code for the MIPS r
7033 chip. This tells the assembler to accept instructions specific to that chip,
7034 and to schedule for that chip's hazards.
7037 Generate code for a particular MIPS cpu. It is exactly equivalent to
7039 except that there are more value of
7046 2000, 3000, 3900, 4000, 4010, 4100, 4111, vr4120, vr4130, vr4181, 4300, 4400,
7047 4600, 4650, 5000, rm5200, rm5230, rm5231, rm5261, rm5721, vr5400, vr5500,
7048 6000, rm7000, 8000, rm9000, 10000, 12000, 4kc, 4km, 4kp, 4ksc, 4kec, 4kem,
7049 4kep, 4ksd, m4k, m4kp, 24kc, 24kf, 24kx, 24kec, 24kef, 24kex, 34kc, 34kf,
7050 34kx, 74kc, 74kf, 74kx, 5kc, 5kf, 20kc, 25kf, sb1, sb1a
7054 Schedule and tune for a particular MIPS cpu. Valid
7056 values are identical to
7057 .Li -march= Va cpu .
7060 Record which ABI the source code uses. The recognized arguments are:
7070 Equivalent to adding
7074 to the beginning of the assembler input.See Section
7075 .Dq MIPS symbol sizes .
7078 This option is ignored. It is accepted for command-line compatibility with
7079 other assemblers, which use it to turn off C style preprocessing. With GNU
7081 there is no need for
7083 because the GNU assembler itself never runs the C preprocessor.
7085 .It --construct-floats
7086 .It --no-construct-floats
7088 .Li --no-construct-floats
7089 option disables the construction of double width floating point constants
7090 by loading the two halves of the value into the two single width floating
7091 point registers that make up the double width register. This feature is useful
7092 if the processor support the FR bit in its status register, and this bit is
7093 known (by the programmer) to be set. This bit prevents the aliasing of the
7094 double width register by the single width registers.
7097 .Li --construct-floats
7098 is selected, allowing construction of these floating point constants.
7103 automatically macro expands certain division and multiplication instructions
7104 to check for overflow and division by zero. This option causes
7106 to generate code to take a trap exception rather than a break exception when
7107 an error is detected. The trap instructions are only supported at Instruction
7108 Set Architecture level 2 and higher.
7112 Generate code to take a break exception rather than a trap exception when
7113 an error is detected. This is the default.
7117 Control generation of
7119 sections. Off by default on IRIX, on elsewhere.
7123 When generating code using the Unix calling conventions (selected by
7126 .Li -mcall_shared ) ,
7127 gas will normally generate code which can go into a shared library. The
7129 option tells gas to generate code which uses the calling convention, but can
7130 not go into a shared library. The resulting code is slightly more efficient.
7131 This option only affects the handling of the
7138 .Ss MIPS ECOFF object code
7139 Assembling for a mips ecoff target supports some additional sections besides
7145 The additional sections are
7147 used for read-only data,
7149 used for small data, and
7151 used for small common objects.
7153 When assembling for ecoff, the assembler uses the
7157 register to form the address of a \(lqsmall object\(rq. Any object in the
7161 sections is considered \(lqsmall\(rq in this sense. For external objects, or for objects
7164 section, you can use the
7167 option to control the size of objects addressed via
7169 the default value is 8, meaning that a reference to any object eight bytes
7176 prevents it from using the
7178 register on the basis of object size (but the assembler uses
7184 in any case). The size of an object in the
7186 section is set by the
7190 directive that defines it. The size of an external object may be set with
7193 directive. For example,
7195 declares that the object at
7197 is 4 bytes in length, whie leaving
7199 otherwise undefined.
7201 Using small ecoff objects requires linker support, and assumes that the
7203 register is correctly initialized (normally done automatically by the startup
7204 code). mips ecoff assembly code must not modify the
7208 .Ss Directives for debugging information
7211 supports several directives used for generating debugging information which
7212 are not support by traditional mips assemblers. These are
7226 The debugging information generated by the three
7228 directives can only be read by gdb, not by traditional mips debuggers (this
7229 enhancement is required to fully support C++ debugging). These directives
7230 are primarily used by compilers, not assembly language programmers!
7232 .Ss Directives to override the size of symbols
7233 The n64 ABI allows symbols to have any 64-bit value. Although this provides
7234 a great deal of flexibility, it means that some macros have much longer expansions
7235 than their 32-bit counterparts. For example, the non-PIC expansion of
7239 .Bd -literal -offset indent
7240 lui $4,%highest(sym)
7242 daddiu $4,$4,%higher(sym)
7243 daddiu $1,$1,%lo(sym)
7248 whereas the 32-bit expansion is simply:
7250 .Bd -literal -offset indent
7252 daddiu $4,$4,%lo(sym)
7255 n64 code is sometimes constructed in such a way that all symbolic constants
7256 are known to have 32-bit values, and in such cases, it's preferable to use
7257 the 32-bit expansion instead of the 64-bit expansion.
7261 directive to tell the assembler that, from this point on, all expressions
7265 .Li Va symbol + Va offset
7266 have 32-bit values. For example:
7268 .Bd -literal -offset indent
7272 sw $4,sym+0x8000($4)
7275 will cause the assembler to treat
7280 as 32-bit values. The handling of non-symbolic addresses is not affected.
7286 block and reverts to the normal behavior. It is also possible to change the
7287 symbol size using the command-line options
7292 These options and directives are always accepted, but at present, they have
7293 no effect for anything other than n64.
7295 .Ss Directives to override the ISA level
7298 supports an additional directive to change the mips Instruction Set Architecture
7300 .Li .set mips Va n .
7302 should be a number from 0 to 5, or 32, 32r2, 64 or 64r2. The values other
7303 than 0 make the assembler accept instructions for the corresponding isa level,
7304 from that point on in the assembly.
7306 affects not only which instructions are permitted, but also how certain macros
7309 restores the isa level to its original level: either the level you selected
7310 with command line options, or the default for your configuration. You can
7311 use this feature to permit specific mips3 instructions while assembling in
7312 32 bit mode. Use this directive with care!
7315 .Li .set arch= Va cpu
7316 directive provides even finer control. It changes the effective CPU target
7317 and allows the assembler to use instructions specific to a particular CPU.
7318 All CPUs supported by the
7320 command line option are also selectable by this directive. The original value
7322 .Li .set arch=default .
7326 puts the assembler into MIPS 16 mode, in which it will assemble instructions
7327 for the MIPS 16 processor. Use
7329 to return to normal 32 bit mode.
7331 Traditional mips assemblers do not support this directive.
7333 .Ss Directives for extending MIPS 16 bit instructions
7334 By default, MIPS 16 instructions are automatically extended to 32 bits when
7335 necessary. The directive
7336 .Li .set noautoextend
7337 will turn this off. When
7338 .Li .set noautoextend
7339 is in effect, any 32 bit instruction must be explicitly extended with the
7342 .Li li.e $4,1000 ) .
7345 may be used to once again automatically extend instructions when necessary.
7347 This directive is only meaningful when in MIPS 16 mode. Traditional mips assemblers
7348 do not support this directive.
7350 .Ss Directive to mark data as an instruction
7355 that the following data is actually instructions. This makes a difference
7356 in MIPS 16 mode: when loading the address of a label which precedes instructions,
7358 automatically adds 1 to the value, so that jumping to the loaded address will
7361 .Ss Directives to save and restore options
7366 may be used to save and restore the current settings for all the options which
7371 directive saves the current settings on a stack. The
7373 directive pops the stack and restores the settings.
7375 These directives can be useful inside an macro which must change an option
7376 such as the ISA level or instruction reordering but does not want to change
7377 the state of the code which invoked the macro.
7379 Traditional mips assemblers do not support these directives.
7381 .Ss Directives to control generation of MIPS ASE instructions
7384 makes the assembler accept instructions from the MIPS-3D Application Specific
7385 Extension from that point on in the assembly. The
7387 directive prevents MIPS-3D instructions from being accepted.
7391 makes the assembler accept instructions from the SmartMIPS Application Specific
7392 Extension to the MIPS32 isa from that point on in the assembly. The
7393 .Li .set nosmartmips
7394 directive prevents SmartMIPS instructions from being accepted.
7398 makes the assembler accept instructions from the MDMX Application Specific
7399 Extension from that point on in the assembly. The
7401 directive prevents MDMX instructions from being accepted.
7405 makes the assembler accept instructions from the DSP Release 1 Application
7406 Specific Extension from that point on in the assembly. The
7408 directive prevents DSP Release 1 instructions from being accepted.
7412 makes the assembler accept instructions from the DSP Release 2 Application
7413 Specific Extension from that point on in the assembly. This dirctive implies
7417 directive prevents DSP Release 2 instructions from being accepted.
7421 makes the assembler accept instructions from the MT Application Specific Extension
7422 from that point on in the assembly. The
7424 directive prevents MT instructions from being accepted.
7426 Traditional mips assemblers do not support these directives.
7428 .Sh PowerPC Dependent Features
7430 The PowerPC chip family includes several successive levels, using the same
7431 core instruction set, but including a few additional instructions at each
7432 level. There are exceptions to this however. For details on what instructions
7433 each variant supports, please see the chip's architecture reference manual.
7435 The following table lists all available PowerPC options.
7439 Generate code for POWER/2 (RIOS2).
7442 Generate code for POWER (RIOS1)
7445 Generate code for PowerPC 601.
7447 .It -mppc, -mppc32, -m603, -m604
7448 Generate code for PowerPC 603/604.
7451 Generate code for PowerPC 403/405.
7454 Generate code for PowerPC 440. BookE and some 405 instructions.
7456 .It -m7400, -m7410, -m7450, -m7455
7457 Generate code for PowerPC 7400/7410/7450/7455.
7460 Generate code for PowerPC 620/625/630.
7462 .It -me500, -me500x2
7463 Generate code for Motorola e500 core complex.
7466 Generate code for Motorola SPE instructions.
7469 Generate code for PowerPC 64, including bridge insns.
7472 Generate code for 64-bit BookE.
7474 .It -mbooke, mbooke32
7475 Generate code for 32-bit BookE.
7478 Generate code for PowerPC e300 family.
7481 Generate code for processors with AltiVec instructions.
7484 Generate code for Power4 architecture.
7487 Generate code for Power5 architecture.
7490 Generate code for Power6 architecture.
7493 Generate code for Cell Broadband Engine architecture.
7496 Generate code Power/PowerPC common instructions.
7499 Generate code for any architecture (PWR/PWRX/PPC).
7502 Allow symbolic names for registers.
7505 Do not allow symbolic names for registers.
7508 Support for GCC's -mrelocatable option.
7510 .It -mrelocatable-lib
7511 Support for GCC's -mrelocatable-lib option.
7514 Set PPC_EMB bit in ELF flags.
7516 .It -mlittle, -mlittle-endian
7517 Generate code for a little endian machine.
7519 .It -mbig, -mbig-endian
7520 Generate code for a big endian machine.
7523 Generate code for Solaris.
7526 Do not generate code for Solaris.
7529 .Ss PowerPC Assembler Directives
7530 A number of assembler directives are available for PowerPC. The following
7531 table is far from complete.
7534 .It .machine "string"
7535 This directive allows you to change the machine for which code is generated.
7537 may be any of the -m cpu selection options (without the -m) enclosed in double
7543 saves the currently selected cpu, which may be restored with
7544 .Li .machine "pop" .
7547 .Sh SPARC Dependent Features
7549 The SPARC chip family includes several successive levels, using the same core
7550 instruction set, but including a few additional instructions at each level.
7551 There are exceptions to this however. For details on what instructions each
7552 variant supports, please see the chip's architecture reference manual.
7556 assumes the core instruction set (SPARC v6), but \(lqbumps\(rq the architecture level
7557 as needed: it switches to successively higher architectures as it encounters
7558 instructions that only exist in the higher levels.
7560 If not configured for SPARC v9 (
7562 GAS will not bump passed sparclite by default, an option must be passed to
7563 enable the v9 instructions.
7565 GAS treats sparclite as being compatible with v8, unless an architecture is
7566 explicitly requested. SPARC v9 is always incompatible with sparclite.
7569 .It -Av6 | -Av7 | -Av8 | -Asparclet | -Asparclite
7570 .It -Av8plus | -Av8plusa | -Av9 | -Av9a
7573 options to select one of the SPARC architectures explicitly. If you select
7574 an architecture explicitly,
7576 reports a fatal error if it encounters an instruction or feature requiring
7577 an incompatible or higher level.
7582 select a 32 bit environment.
7587 select a 64 bit environment and are not available unless GAS is explicitly
7588 configured with 64 bit environment support.
7593 enable the SPARC V9 instruction set with UltraSPARC extensions.
7595 .It -xarch=v8plus | -xarch=v8plusa
7596 For compatibility with the Solaris v9 assembler. These options are equivalent
7597 to -Av8plus and -Av8plusa, respectively.
7600 Warn whenever it is necessary to switch to another level. If an architecture
7601 level is explicitly requested, GAS will not issue warnings until that level
7602 is reached, and will then bump the level as required (except between incompatible
7606 Select the word size, either 32 bits or 64 bits. These options are only available
7607 with the ELF object file format, and require that the necessary BFD support
7611 .Ss Enforcing aligned data
7612 SPARC GAS normally permits data to be misaligned. For example, it permits
7615 pseudo-op to be used on a byte boundary. However, the native SunOS and Solaris
7616 assemblers issue an error when they see misaligned data.
7619 .Li --enforce-aligned-data
7620 option to make SPARC GAS also issue an error about misaligned data, just as
7621 the SunOS and Solaris assemblers do.
7624 .Li --enforce-aligned-data
7625 option is not the default because gcc issues misaligned data pseudo-ops when
7626 it initializes certain packed data structures (structures defined using the
7628 attribute). You may have to assemble with GAS in order to initialize packed
7629 data structures in your own code.
7632 The Sparc uses ieee floating-point numbers.
7634 .Ss Sparc Machine Directives
7635 The Sparc version of
7637 supports the following additional machine directives:
7641 This must be followed by the desired alignment in bytes.
7644 This must be followed by a symbol name, a positive number, and
7646 This behaves somewhat like
7648 but the syntax is different.
7651 This is functionally identical to
7657 directive produces native word sized value, ie. if assembling with -32 it
7660 if assembling with -64 it is equivalent to
7664 This directive is ignored. Any text following it on the same line is also
7668 This directive declares use of a global application or system register. It
7669 must be followed by a register name %g2, %g3, %g6 or %g7, comma and the symbol
7670 name for that register. If symbol name is
7672 it is a scratch register, if it is
7674 it just suppresses any errors about using undeclared global register, but
7675 does not emit any information about it into the object file. This can be useful
7676 e.g. if you save the register before use and restore it after.
7679 This must be followed by a symbol name, a positive number, and
7681 This behaves somewhat like
7683 but the syntax is different.
7686 This must be followed by
7698 This is functionally identical to the
7705 directive produces 32 bit values, instead of the 16 bit values it produces
7706 on many other machines.
7709 On the Sparc V9 processor, the
7711 directive produces 64 bit values.
7715 Your bug reports play an essential role in making
7719 Reporting a bug may help you by bringing a solution to your problem, or it
7720 may not. But in any case the principal function of a bug report is to help
7721 the entire community by making the next version of
7723 work better. Bug reports are your contribution to the maintenance of
7726 In order for a bug report to serve its purpose, you must include the information
7727 that enables us to fix the bug.
7729 .Ss Have You Found a Bug?
7730 If you are not sure whether you have found a bug, here are some guidelines:
7734 If the assembler gets a fatal signal, for any input whatever, that is a
7736 bug. Reliable assemblers never crash.
7741 produces an error message for valid input, that is a bug.
7746 does not produce an error message for invalid input, that is a bug. However,
7747 you should note that your idea of \(lqinvalid input\(rq might be our idea of \(lqan extension\(rq
7748 or \(lqsupport for traditional practice\(rq.
7751 If you are an experienced user of assemblers, your suggestions for improvement
7754 are welcome in any case.
7757 .Ss How to Report Bugs
7758 A number of companies and individuals offer support for GNU products. If you
7761 from a support organization, we recommend you contact that organization first.
7763 You can find contact information for many support companies and individuals
7766 in the GNU Emacs distribution.
7768 The fundamental principle of reporting bugs usefully is this:
7769 .Sy report all the facts .
7770 If you are not sure whether to state a fact or leave it out, state it!
7772 Often people omit facts because they think they know what causes the problem
7773 and assume that some details do not matter. Thus, you might assume that the
7774 name of a symbol you use in an example does not matter. Well, probably it
7775 does not, but one cannot be sure. Perhaps the bug is a stray memory reference
7776 which happens to fetch from the location where that name is stored in memory;
7777 perhaps, if the name were different, the contents of that location would fool
7778 the assembler into doing the right thing despite the bug. Play it safe and
7779 give a specific, complete example. That is the easiest thing for you to do,
7780 and the most helpful.
7782 Keep in mind that the purpose of a bug report is to enable us to fix the bug
7783 if it is new to us. Therefore, always write your bug reports on the assumption
7784 that the bug has not been reported previously.
7786 Sometimes people give a few sketchy facts and ask, \(lqDoes this ring a bell?\(rq
7787 This cannot help us fix a bug, so it is basically useless. We respond by asking
7788 for enough details to enable us to investigate. You might as well expedite
7789 matters by sending them to begin with.
7791 To enable us to fix the bug, you should include all these things:
7798 announces it if you start it with the
7802 Without this, we will not know whether there is any point in looking for the
7803 bug in the current version of
7807 Any patches you may have applied to the
7812 The type of machine you are using, and the operating system name and version
7816 What compiler (and its version) was used to compile
7823 The command arguments you gave the assembler to assemble your example and
7824 observe the bug. To guarantee you will not omit something important, list
7825 them all. A copy of the Makefile (or the output from make) is sufficient.
7827 If we were to try to guess the arguments, we would probably guess wrong and
7828 then we might not encounter the bug.
7831 A complete input file that will reproduce the bug. If the bug is observed
7832 when the assembler is invoked via a compiler, send the assembler source, not
7833 the high level language source. Most compilers will produce the assembler
7834 source when run with the
7836 option. If you are using
7839 .Li -v --save-temps ;
7840 this will save the assembler source in a file with an extension of
7842 and also show you exactly how
7847 A description of what behavior you observe that you believe is incorrect.
7848 For example, \(lqIt gets a fatal signal.\(rq
7850 Of course, if the bug is that
7852 gets a fatal signal, then we will certainly notice it. But if the bug is incorrect
7853 output, we might not notice unless it is glaringly wrong. You might as well
7854 not give us a chance to make a mistake.
7856 Even if the problem you experience is a fatal signal, you should still say
7857 so explicitly. Suppose something strange is going on, such as, your copy of
7859 is out of sync, or you have encountered a bug in the C library on your system.
7860 (This has happened!) Your copy might crash and ours would not. If you told
7861 us to expect a crash, then when ours fails to crash, we would know that the
7862 bug was not happening for us. If you had not told us to expect a crash, then
7863 we would not be able to draw any conclusion from our observations.
7866 If you wish to suggest changes to the
7868 source, send us context diffs, as generated by
7875 option. Always send diffs from the old file to the new file. If you even discuss
7878 source, refer to it by context, not by line number.
7880 The line numbers in our development sources will not match those in your sources.
7881 Your line numbers would convey no useful information to us.
7884 Here are some things that are not necessary:
7888 A description of the envelope of the bug.
7890 Often people who encounter a bug spend a lot of time investigating which changes
7891 to the input file will make the bug go away and which changes will not affect
7894 This is often time consuming and not very useful, because the way we will
7895 find the bug is by running a single example under the debugger with breakpoints,
7896 not by pure deduction from a series of examples. We recommend that you save
7897 your time for something else.
7899 Of course, if you can find a simpler example to report
7901 of the original one, that is a convenience for us. Errors in the output will
7902 be easier to spot, running under the debugger will take less time, and so
7905 However, simplification is not vital; if you do not want to do this, report
7906 the bug anyway and send us the entire test case you used.
7909 A patch for the bug.
7911 A patch for the bug does help us if it is a good one. But do not omit the
7912 necessary information, such as the test case, on the assumption that a patch
7913 is all we need. We might see problems with your patch and decide to fix the
7914 problem another way, or we might not understand it at all.
7916 Sometimes with a program as complicated as
7918 it is very hard to construct an example that will make the program follow
7919 a certain path through the code. If you do not send us the example, we will
7920 not be able to construct one, so we will not be able to verify that the bug
7923 And if we cannot understand what bug you are trying to fix, or why your patch
7924 should be an improvement, we will not install it. A test case will help us
7928 A guess about what the bug is or what it depends on.
7930 Such guesses are usually wrong. Even we cannot guess right about such things
7931 without first using the debugger to find the facts.
7934 .Sh Acknowledgements
7935 If you have contributed to GAS and your name isn't listed here, it is not
7936 meant as a slight. We just don't know about it. Send mail to the maintainer,
7937 and we'll correct the situation. Currently the maintainer is Ken Raeburn (email
7939 .Li raeburn@cyGNUs.com ) .
7941 Dean Elsner wrote the original GNU assembler for the VAX.
7943 Jay Fenlason maintained GAS for a while, adding support for GDB-specific debug
7944 information and the 68k series machines, most of the preprocessing pass, and
7945 extensive changes in
7950 K. Richard Pixley maintained GAS for a while, adding various enhancements
7951 and many bug fixes, including merging support for several processors, breaking
7952 GAS up to handle multiple object file format back ends (including heavy rewrite,
7953 testing, an integration of the coff and b.out back ends), adding configuration
7954 including heavy testing and verification of cross assemblers and file splits
7955 and renaming, converted GAS to strictly ANSI C including full prototypes,
7956 added support for m680[34]0 and cpu32, did considerable work on i960 including
7957 a COFF port (including considerable amounts of reverse engineering), a SPARC
7958 opcode file rewrite, DECstation, rs6000, and hp300hpux host ports, updated
7959 \(lqknow\(rq assertions and made them work, much other reorganization, cleanup, and
7962 Ken Raeburn wrote the high-level BFD interface code to replace most of the
7963 code in format-specific I/O modules.
7965 The original VMS support was contributed by David L. Kashtan. Eric Youngdale
7966 has done much work with it since.
7968 The Intel 80386 machine description was written by Eliot Dresselhaus.
7970 Minh Tran-Le at IntelliCorp contributed some AIX 386 support.
7972 The Motorola 88k machine description was contributed by Devon Bowen of Buffalo
7973 University and Torbjorn Granlund of the Swedish Institute of Computer Science.
7975 Keith Knowles at the Open Software Foundation wrote the original MIPS back
7979 and contributed Rose format support (which hasn't been merged in yet). Ralph
7980 Campbell worked with the MIPS code to support a.out format.
7982 Support for the Zilog Z8k and Renesas H8/300 processors (tc-z8k, tc-h8300),
7983 and IEEE 695 object file format (obj-ieee), was written by Steve Chamberlain
7984 of CyGNUs Support. Steve also modified the COFF back end to use BFD for some
7985 low-level operations, for use with the H8/300 and AMD 29k targets.
7987 John Gilmore built the AMD 29000 support, added
7989 support, and simplified the configuration of which versions accept which directives.
7990 He updated the 68k machine description so that Motorola's opcodes always produced
7991 fixed-size instructions (e.g.,
7993 while synthetic instructions remained shrinkable (
7995 John fixed many bugs, including true tested cross-compilation support, and
7996 one bug in relaxation that took a week and required the proverbial one-bit
7999 Ian Lance Taylor of CyGNUs Support merged the Motorola and MIT syntax for
8000 the 68k, completed support for some COFF targets (68k, i386 SVR3, and SCO
8001 Unix), added support for MIPS ECOFF and ELF targets, wrote the initial RS/6000
8002 and PowerPC assembler, and made a few other minor patches.
8004 Steve Chamberlain made GAS able to generate listings.
8006 Hewlett-Packard contributed support for the HP9000/300.
8008 Jeff Law wrote GAS and BFD support for the native HPPA object format (SOM)
8009 along with a fairly extensive HPPA testsuite (for both SOM and ELF object
8010 formats). This work was supported by both the Center for Software Science
8011 at the University of Utah and CyGNUs Support.
8013 Support for ELF format files has been worked on by Mark Eichin of CyGNUs Support
8014 (original, incomplete implementation for SPARC), Pete Hoogenboom and Jeff
8015 Law at the University of Utah (HPPA mainly), Michael Meissner of the Open
8016 Software Foundation (i386 mainly), and Ken Raeburn of CyGNUs Support (sparc,
8017 and some initial 64-bit support).
8019 Linas Vepstas added GAS support for the ESA/390 \(lqIBM 370\(rq architecture.
8021 Richard Henderson rewrote the Alpha assembler. Klaus Kaempf wrote GAS and
8022 BFD support for openVMS/Alpha.
8024 Timothy Wall, Michael Hayes, and Greg Smart contributed to the various tic*
8027 David Heine, Sterling Augustine, Bob Wilson and John Ruttenberg from Tensilica,
8028 Inc. added support for Xtensa processors.
8030 Several engineers at CyGNUs Support have also provided many small bug fixes
8031 and configuration enhancements.
8033 Many others have contributed large or small bugfixes and enhancements. If
8034 you have contributed significant work and are not mentioned on this list,
8035 and want to be, let us know. Some of the history has been lost; we are not
8036 intentionally leaving anyone out.
8038 .Sh GNU Free Documentation License
8039 .Bd -filled -offset indent
8040 Copyright (C) 2000, 2003 Free Software Foundation, Inc. 51 Franklin Street,
8041 Fifth Floor, Boston, MA 02110-1301 USA
8043 Everyone is permitted to copy and distribute verbatim copies of this license
8044 document, but changing it is not allowed.
8051 The purpose of this License is to make a manual, textbook, or other written
8052 document \(lqfree\(rq in the sense of freedom: to assure everyone the effective freedom
8053 to copy and redistribute it, with or without modifying it, either commercially
8054 or noncommercially. Secondarily, this License preserves for the author and
8055 publisher a way to get credit for their work, while not being considered responsible
8056 for modifications made by others.
8058 This License is a kind of \(lqcopyleft\(rq, which means that derivative works of the
8059 document must themselves be free in the same sense. It complements the GNU
8060 General Public License, which is a copyleft license designed for free software.
8062 We have designed this License in order to use it for manuals for free software,
8063 because free software needs free documentation: a free program should come
8064 with manuals providing the same freedoms that the software does. But this
8065 License is not limited to software manuals; it can be used for any textual
8066 work, regardless of subject matter or whether it is published as a printed
8067 book. We recommend this License principally for works whose purpose is instruction
8071 APPLICABILITY AND DEFINITIONS
8073 This License applies to any manual or other work that contains a notice placed
8074 by the copyright holder saying it can be distributed under the terms of this
8075 License. The \(lqDocument\(rq, below, refers to any such manual or work. Any member
8076 of the public is a licensee, and is addressed as \(lqyou.\(rq
8078 A \(lqModified Version\(rq of the Document means any work containing the Document
8079 or a portion of it, either copied verbatim, or with modifications and/or translated
8080 into another language.
8082 A \(lqSecondary Section\(rq is a named appendix or a front-matter section of the Document
8083 that deals exclusively with the relationship of the publishers or authors
8084 of the Document to the Document's overall subject (or to related matters)
8085 and contains nothing that could fall directly within that overall subject.
8086 (For example, if the Document is in part a textbook of mathematics, a Secondary
8087 Section may not explain any mathematics.) The relationship could be a matter
8088 of historical connection with the subject or with related matters, or of legal,
8089 commercial, philosophical, ethical or political position regarding them.
8091 The \(lqInvariant Sections\(rq are certain Secondary Sections whose titles are designated,
8092 as being those of Invariant Sections, in the notice that says that the Document
8093 is released under this License.
8095 The \(lqCover Texts\(rq are certain short passages of text that are listed, as Front-Cover
8096 Texts or Back-Cover Texts, in the notice that says that the Document is released
8099 A \(lqTransparent\(rq copy of the Document means a machine-readable copy, represented
8100 in a format whose specification is available to the general public, whose
8101 contents can be viewed and edited directly and straightforwardly with generic
8102 text editors or (for images composed of pixels) generic paint programs or
8103 (for drawings) some widely available drawing editor, and that is suitable
8104 for input to text formatters or for automatic translation to a variety of
8105 formats suitable for input to text formatters. A copy made in an otherwise
8106 Transparent file format whose markup has been designed to thwart or discourage
8107 subsequent modification by readers is not Transparent. A copy that is not
8108 \(lqTransparent\(rq is called \(lqOpaque.\(rq
8110 Examples of suitable formats for Transparent copies include plain ASCII without
8111 markup, Texinfo input format, LaTeX input format, SGML or XML using a publicly
8112 available DTD, and standard-conforming simple HTML designed for human modification.
8113 Opaque formats include PostScript, PDF, proprietary formats that can be read
8114 and edited only by proprietary word processors, SGML or XML for which the
8115 DTD and/or processing tools are not generally available, and the machine-generated
8116 HTML produced by some word processors for output purposes only.
8118 The \(lqTitle Page\(rq means, for a printed book, the title page itself, plus such
8119 following pages as are needed to hold, legibly, the material this License
8120 requires to appear in the title page. For works in formats which do not have
8121 any title page as such, \(lqTitle Page\(rq means the text near the most prominent
8122 appearance of the work's title, preceding the beginning of the body of the
8128 You may copy and distribute the Document in any medium, either commercially
8129 or noncommercially, provided that this License, the copyright notices, and
8130 the license notice saying this License applies to the Document are reproduced
8131 in all copies, and that you add no other conditions whatsoever to those of
8132 this License. You may not use technical measures to obstruct or control the
8133 reading or further copying of the copies you make or distribute. However,
8134 you may accept compensation in exchange for copies. If you distribute a large
8135 enough number of copies you must also follow the conditions in section 3.
8137 You may also lend copies, under the same conditions stated above, and you
8138 may publicly display copies.
8143 If you publish printed copies of the Document numbering more than 100, and
8144 the Document's license notice requires Cover Texts, you must enclose the copies
8145 in covers that carry, clearly and legibly, all these Cover Texts: Front-Cover
8146 Texts on the front cover, and Back-Cover Texts on the back cover. Both covers
8147 must also clearly and legibly identify you as the publisher of these copies.
8148 The front cover must present the full title with all words of the title equally
8149 prominent and visible. You may add other material on the covers in addition.
8150 Copying with changes limited to the covers, as long as they preserve the title
8151 of the Document and satisfy these conditions, can be treated as verbatim copying
8154 If the required texts for either cover are too voluminous to fit legibly,
8155 you should put the first ones listed (as many as fit reasonably) on the actual
8156 cover, and continue the rest onto adjacent pages.
8158 If you publish or distribute Opaque copies of the Document numbering more
8159 than 100, you must either include a machine-readable Transparent copy along
8160 with each Opaque copy, or state in or with each Opaque copy a publicly-accessible
8161 computer-network location containing a complete Transparent copy of the Document,
8162 free of added material, which the general network-using public has access
8163 to download anonymously at no charge using public-standard network protocols.
8164 If you use the latter option, you must take reasonably prudent steps, when
8165 you begin distribution of Opaque copies in quantity, to ensure that this Transparent
8166 copy will remain thus accessible at the stated location until at least one
8167 year after the last time you distribute an Opaque copy (directly or through
8168 your agents or retailers) of that edition to the public.
8170 It is requested, but not required, that you contact the authors of the Document
8171 well before redistributing any large number of copies, to give them a chance
8172 to provide you with an updated version of the Document.
8177 You may copy and distribute a Modified Version of the Document under the conditions
8178 of sections 2 and 3 above, provided that you release the Modified Version
8179 under precisely this License, with the Modified Version filling the role of
8180 the Document, thus licensing distribution and modification of the Modified
8181 Version to whoever possesses a copy of it. In addition, you must do these
8182 things in the Modified Version:
8184 A. Use in the Title Page (and on the covers, if any) a title distinct from
8185 that of the Document, and from those of previous versions (which should, if
8186 there were any, be listed in the History section of the Document). You may
8187 use the same title as a previous version if the original publisher of that
8188 version gives permission. B. List on the Title Page, as authors, one or more
8189 persons or entities responsible for authorship of the modifications in the
8190 Modified Version, together with at least five of the principal authors of
8191 the Document (all of its principal authors, if it has less than five). C.
8192 State on the Title page the name of the publisher of the Modified Version,
8193 as the publisher. D. Preserve all the copyright notices of the Document.
8194 E. Add an appropriate copyright notice for your modifications adjacent to
8195 the other copyright notices. F. Include, immediately after the copyright
8196 notices, a license notice giving the public permission to use the Modified
8197 Version under the terms of this License, in the form shown in the Addendum
8198 below. G. Preserve in that license notice the full lists of Invariant Sections
8199 and required Cover Texts given in the Document's license notice. H. Include
8200 an unaltered copy of this License. I. Preserve the section entitled \(lqHistory\(rq,
8201 and its title, and add to it an item stating at least the title, year, new
8202 authors, and publisher of the Modified Version as given on the Title Page.
8203 If there is no section entitled \(lqHistory\(rq in the Document, create one stating
8204 the title, year, authors, and publisher of the Document as given on its Title
8205 Page, then add an item describing the Modified Version as stated in the previous
8206 sentence. J. Preserve the network location, if any, given in the Document
8207 for public access to a Transparent copy of the Document, and likewise the
8208 network locations given in the Document for previous versions it was based
8209 on. These may be placed in the \(lqHistory\(rq section. You may omit a network location
8210 for a work that was published at least four years before the Document itself,
8211 or if the original publisher of the version it refers to gives permission.
8212 K. In any section entitled \(lqAcknowledgements\(rq or \(lqDedications\(rq, preserve the section's
8213 title, and preserve in the section all the substance and tone of each of the
8214 contributor acknowledgements and/or dedications given therein. L. Preserve
8215 all the Invariant Sections of the Document, unaltered in their text and in
8216 their titles. Section numbers or the equivalent are not considered part of
8217 the section titles. M. Delete any section entitled \(lqEndorsements.\(rq Such a section
8218 may not be included in the Modified Version. N. Do not retitle any existing
8219 section as \(lqEndorsements\(rq or to conflict in title with any Invariant Section.
8221 If the Modified Version includes new front-matter sections or appendices that
8222 qualify as Secondary Sections and contain no material copied from the Document,
8223 you may at your option designate some or all of these sections as invariant.
8224 To do this, add their titles to the list of Invariant Sections in the Modified
8225 Version's license notice. These titles must be distinct from any other section
8228 You may add a section entitled \(lqEndorsements\(rq, provided it contains nothing
8229 but endorsements of your Modified Version by various parties--for example,
8230 statements of peer review or that the text has been approved by an organization
8231 as the authoritative definition of a standard.
8233 You may add a passage of up to five words as a Front-Cover Text, and a passage
8234 of up to 25 words as a Back-Cover Text, to the end of the list of Cover Texts
8235 in the Modified Version. Only one passage of Front-Cover Text and one of Back-Cover
8236 Text may be added by (or through arrangements made by) any one entity. If
8237 the Document already includes a cover text for the same cover, previously
8238 added by you or by arrangement made by the same entity you are acting on behalf
8239 of, you may not add another; but you may replace the old one, on explicit
8240 permission from the previous publisher that added the old one.
8242 The author(s) and publisher(s) of the Document do not by this License give
8243 permission to use their names for publicity for or to assert or imply endorsement
8244 of any Modified Version.
8249 You may combine the Document with other documents released under this License,
8250 under the terms defined in section 4 above for modified versions, provided
8251 that you include in the combination all of the Invariant Sections of all of
8252 the original documents, unmodified, and list them all as Invariant Sections
8253 of your combined work in its license notice.
8255 The combined work need only contain one copy of this License, and multiple
8256 identical Invariant Sections may be replaced with a single copy. If there
8257 are multiple Invariant Sections with the same name but different contents,
8258 make the title of each such section unique by adding at the end of it, in
8259 parentheses, the name of the original author or publisher of that section
8260 if known, or else a unique number. Make the same adjustment to the section
8261 titles in the list of Invariant Sections in the license notice of the combined
8264 In the combination, you must combine any sections entitled \(lqHistory\(rq in the
8265 various original documents, forming one section entitled \(lqHistory\(rq; likewise
8266 combine any sections entitled \(lqAcknowledgements\(rq, and any sections entitled
8267 \(lqDedications.\(rq You must delete all sections entitled \(lqEndorsements.\(rq
8270 COLLECTIONS OF DOCUMENTS
8272 You may make a collection consisting of the Document and other documents released
8273 under this License, and replace the individual copies of this License in the
8274 various documents with a single copy that is included in the collection, provided
8275 that you follow the rules of this License for verbatim copying of each of
8276 the documents in all other respects.
8278 You may extract a single document from such a collection, and distribute it
8279 individually under this License, provided you insert a copy of this License
8280 into the extracted document, and follow this License in all other respects
8281 regarding verbatim copying of that document.
8284 AGGREGATION WITH INDEPENDENT WORKS
8286 A compilation of the Document or its derivatives with other separate and independent
8287 documents or works, in or on a volume of a storage or distribution medium,
8288 does not as a whole count as a Modified Version of the Document, provided
8289 no compilation copyright is claimed for the compilation. Such a compilation
8290 is called an \(lqaggregate\(rq, and this License does not apply to the other self-contained
8291 works thus compiled with the Document, on account of their being thus compiled,
8292 if they are not themselves derivative works of the Document.
8294 If the Cover Text requirement of section 3 is applicable to these copies of
8295 the Document, then if the Document is less than one quarter of the entire
8296 aggregate, the Document's Cover Texts may be placed on covers that surround
8297 only the Document within the aggregate. Otherwise they must appear on covers
8298 around the whole aggregate.
8303 Translation is considered a kind of modification, so you may distribute translations
8304 of the Document under the terms of section 4. Replacing Invariant Sections
8305 with translations requires special permission from their copyright holders,
8306 but you may include translations of some or all Invariant Sections in addition
8307 to the original versions of these Invariant Sections. You may include a translation
8308 of this License provided that you also include the original English version
8309 of this License. In case of a disagreement between the translation and the
8310 original English version of this License, the original English version will
8316 You may not copy, modify, sublicense, or distribute the Document except as
8317 expressly provided for under this License. Any other attempt to copy, modify,
8318 sublicense or distribute the Document is void, and will automatically terminate
8319 your rights under this License. However, parties who have received copies,
8320 or rights, from you under this License will not have their licenses terminated
8321 so long as such parties remain in full compliance.
8324 FUTURE REVISIONS OF THIS LICENSE
8326 The Free Software Foundation may publish new, revised versions of the GNU
8327 Free Documentation License from time to time. Such new versions will be similar
8328 in spirit to the present version, but may differ in detail to address new
8329 problems or concerns. See http://www.gnu.org/copyleft/.
8331 Each version of the License is given a distinguishing version number. If the
8332 Document specifies that a particular numbered version of this License \(lqor any
8333 later version\(rq applies to it, you have the option of following the terms and
8334 conditions either of that specified version or of any later version that has
8335 been published (not as a draft) by the Free Software Foundation. If the Document
8336 does not specify a version number of this License, you may choose any version
8337 ever published (not as a draft) by the Free Software Foundation.
8340 .Ss ADDENDUM: How to use this License for your documents
8341 To use this License in a document you have written, include a copy of the
8342 License in the document and put the following copyright and license notices
8343 just after the title page:
8345 .Bd -literal -offset indent
8347 Copyright (C) year your name.
8348 Permission is granted to copy, distribute and/or modify this document
8349 under the terms of the GNU Free Documentation License, Version 1.1
8350 or any later version published by the Free Software Foundation;
8351 with the Invariant Sections being list their titles, with the
8352 Front-Cover Texts being list, and with the Back-Cover Texts being list.
8353 A copy of the license is included in the section entitled "GNU
8354 Free Documentation License."
8358 If you have no Invariant Sections, write \(lqwith no Invariant Sections\(rq instead
8359 of saying which ones are invariant. If you have no Front-Cover Texts, write
8360 \(lqno Front-Cover Texts\(rq instead of \(lqFront-Cover Texts being
8362 \(rq; likewise for Back-Cover Texts.
8364 If your document contains nontrivial examples of program code, we recommend
8365 releasing these examples in parallel under your choice of free software license,
8366 such as the GNU General Public License, to permit their use in free software.
projects / FreeBSD / FreeBSD.git / blob