as Command

Purpose

Reads and assembles a source file.

Syntax

as [ -a Option[:Option] ] [ -o ObjectFile ] [ -n Name ] [ -u ] [ -l [ ListFile ] ] [ -W | -w ] [ -x [ XCrossFile ] ] [ -s [ ListFile ]] [ -m ModeName ][-M][-Eoff|on ] [ -p off|on ] [ -i ] [ -v ] [ File ]

Description

The as command reads and assembles the named File (by convention, this file ends with a .s suffix). If you do not specify a File, the as command reads and assembles standard input. It stores its output, by default, in a file named a.out. The output is stored in the XCOFF file format.

All flags for the as command are optional.

Flags

-a Option[:Option]

Specifies assembler options. The following options are defined:

32

Assemble the source file in 32-bit mode. This is the default mode. You can also specify this mode by using the OBJECT_MODE environment variable.

64

Assemble the source file in 64-bit mode. You can also specify this mode by using the OBJECT_MODE environment variable.

align-prefixed-csect=<yes/no>

Specifies whether the alignment of a control section (csect) that contains prefixed instructions will be increased to at least a 64-byte boundary, if necessary. 64-byte is the minimum alignment which ensures that the prefixed instructions are aligned properly when assembled programs are linked. If you specify yes for the align-prefixed-csect option, the alignment of csects that contain the prefixed instructions is increased, if necessary. If you specify no for the align-prefixed-csect option and the -w flag is used on the command line, a warning message is displayed if a prefixed instruction is part of a csect with an alignment which is not strict enough. For more information, see the .align pseudo-op.

align-prefixed-op=<yes/no>

Specifies whether a prefixed instruction is aligned by preceding the instruction with a no-op instruction when the prefixed instruction would cross a 64-byte boundary. If you specify yes for the align-prefixed-op option, prefixed instructions are aligned, if required. If you specify no for the align-prefixed-op option and the -w flag is used on the command line, a warning message is displayed if a prefixed instruction crosses a 64-byte boundary. For more information, see the .align pseudo-op.

You can specify multiple options with the -a parameter. If you specify conflicting flags, the succeeding flags override the preceding flags. You can specify multiple options that are separated by colons, with the -a parameter, as shown in the following example:

-a 64:align-prefixed-csect=no

-l[ListFile]

Produces an assembler listing. If you do not specify a file name, a default name is produced by replacing the suffix extension of the source file name with a .lst extension. By convention, the source file suffix is a .s. For example:

sourcefile.xyz

produces a default name of:

sourcefile.lst

If the source code is from standard input and the -l flag is used without specifying an assembler-listing file name, the listing file name is a.lst.

-m ModeName

Indicates the assembly mode. This flag has lower priority than the .machine pseudo-op.

If this flag is not used and no .machine pseudo-op is present in the source program, the default assembly mode is used. The default assembly mode has the POWER® family/PowerPC® intersection as the target environment, but treats all POWER family/PowerPC incompatibility errors (including instructions outside the POWER family/PowerPC intersection and invalid form errors) as instructional warnings.

If an assembly mode that is not valid is specified and no .machine pseudo-op is present in the source program, an error is reported and the default assembly mode is used for instruction validation in pass 1 of the assembler.

If the -m flag is used, the ModeName variable can specify one of the following values:

""

Explicitly specifies the default assembly mode that has the POWER family/PowerPC intersection as the target environment, but treats instructions outside the POWER family/PowerPC intersection and invalid form errors as instructional warnings. A space is required between -m and the null string argument (two double quotation marks).

com

Specifies the POWER family/PowerPC intersection mode. A source program can only contain instructions that are common to both POWER family and PowerPC; any other instruction causes an error. Any instruction with an invalid form causes errors, terminates the assembly process, and results in no object code being generated. This is the default value when assembling in 32-bit mode.

Note: Certain POWER family instructions are supported by the PowerPC 601 RISC Microprocessor, but do not conform to the PowerPC architecture. These instructions cause errors when using the com assembly mode.

any

Specifies the indiscriminate mode. The assembler generates object code for any recognized instruction, regardless of architecture. This mode is used primarily for operating system development and for testing and debugging purposes.

Note: All POWER family and PowerPC incompatibility errors are ignored when using the any assembly mode, and no warnings are generated.

ppc

Specifies the PowerPC64-bit mode. A source program can only contain PowerPC instructions. Any other instruction causes an error.

Note:

1. The PowerPC optional instructions are not implemented in every PowerPC processor and do not belong to the ppc mode. These instructions generate an error if they appear in a source program that is assembled using the ppc assembly mode.
2. Certain instructions conform to the PowerPC architecture, but are not supported by the PowerPC 601 RISC Microprocessor.

ppc64

Specifies the PowerPC64-bit mode. A source program can contain 64-bit PowerPC instructions. This is the default value when assembling in 64-bit mode.

pwr

Specifies the POWER mode. A source program can only contain instructions that are valid for the POWER implementation of the POWER architecture.

pwr2 or pwrx

Specifies the POWER2 mode. A source program can only contain instructions that are valid for the POWER2 implementation of the POWER architecture. pwr2 is the preferred value. The alternate assembly mode value pwrx means the same thing as pwr2.

Note: The POWER implementation instruction set is a subset of the POWER2 implementation instruction set.

pwr4 or 620

Specifies the PowerPC64 mode. A source program can only contain instructions that are valid for POWER4 compatible processors.

601

Specifies the PowerPC 601 RISC Microprocessor mode. A source program can only contain instructions that are valid for the PowerPC 601 RISC Microprocessor.

The PowerPC 601 RISC Microprocessor design was completed before the POWER processor-based platform. Some PowerPC instructions are not be supported by the PowerPC 601 RISC Microprocessor.

Attention: The PowerPC 601 RISC Microprocessor implements the POWER Architecture plus some POWER family instructions that are not included in the PowerPC architecture. This allows existing POWER applications to run with acceptable performance on PowerPC processor-based systems.

The PowerPC 601 RISC Microprocessor implements the POWER processor-based platform plus some POWER family instructions are not included in the POWER processor-based platform. This allows existing POWER applications to run with acceptable performance on POWER processor-based systems.

603

Specifies the PowerPC 603 RISC Microprocessor mode. A source program can only contain instructions that are valid for the PowerPC 603 RISC Microprocessor.

604

Specifies the PowerPC 604 RISC Microprocessor mode. A source program can only contain instructions that are valid for the PowerPC 604 RISC Microprocessor.

ppc970 or 970

Specifies the PowerPC 970 mode. A source program can only contain instructions that are valid for PowerPC 970 compatible processors.

A35

Specifies the A35 mode. A source program can only contain instructions that are valid for the A35.

pwr5

Specifies the POWER5 mode. A source program can only contain instructions that are valid for POWER5 compatible processors.

pwr5x

Specifies the POWER5+ mode. A source program can only contain instructions that are valid for POWER5+ compatible processors.

pwr6

Specifies the POWER6® mode. A source program can only contain instructions that are valid for POWER6 compatible processors.

pwr6e

Specifies the POWER6+ mode. A source program can only contain instructions that are valid for POWER6+ compatible processors.

pwr7

Specifies the POWER7® mode. A source program can only contain instructions that are valid for POWER7 compatible processors.

pwr8

Specifies the POWER8® mode. A source program can only contain instructions that are valid for POWER8 compatible processors.

pwr9

Specifies the POWER9™ mode. A source program can only contain instructions that are valid for POWER9 compatible processors.

pwr10

Specifies the POWER10 mode. A source program can only contain instructions that are valid for POWER10 compatible processors.

-M

Lists the assembly modes that are valid for instructions listed in the input file or list instructions that are valid for the specified assembly mode.

When used with the -m flag, the assembler lists all the instructions that are valid in the assembly mode specified with the -m flag. Any other flags specified on the command line must be valid, but they are ignored. The input file is also ignored.

When used without the -m flag, the assembler reads lines from the specified input file, or from standard input if no input file was specified. Any other flags specified on the command line must be valid, but they are ignored. If a line of input begins with a valid instruction mnemonic, the assembler prints all the assembly modes for which the instruction is valid. If a line begins with a label, the label is removed before the line is checked for a valid instruction. Lines that do not begin with a valid instruction are ignored. Most valid assembler source files can be used as the input file when the -M flag is used, as long as instruction mnemonics are separated from operands by white space.

Note: The assembler does not generate an object file when the -M flag is used.

-n Name

Specifies the name that appears in the header of the assembler listing. By default, the header contains the name of the assembler source file.

-o ObjectFile

Writes the output of the assembly process to the specified file instead of to the a.out file.

-s[ListFile]

Indicates whether or not a mnemonics cross-reference for POWER family and PowerPC is included in the assembler listing. If this flag is omitted, no mnemonics cross-reference is produced. If this flag is used, the assembler listing will have POWER family mnemonics if the source contains PowerPC mnemonics, and will have PowerPC mnemonics if the source contains POWER family mnemonics.

The mnemonics cross-reference is restricted to instructions that have different mnemonics in the POWER family and PowerPC, but that have the same op code, function, and input operand format.

Because the -s flag is used to change the assembler-listing format, it implies the -l flag. If both option flags are used and different assembler-listing file names (specified by the ListFile variable) are given, the listing file name specified by the ListFile variable used with the -l flag is used. If an assembler-listing file name is not specified with either the -l or -s flag, a default assembler listing file name is produced by replacing the suffix extension of the source file name with a .lst extension.

-u

Accepts an undefined symbol as an extern so that an error message is not displayed. Otherwise, undefined symbols are flagged with error messages.

-W

Turns off all warning message reporting, including the instructional warning messages (the POWER family and PowerPC incompatibility warnings).

-w

Turns on warning message reporting, including reporting of instructional warning messages (the POWER family and PowerPC incompatibility warnings).

Note: When neither -W nor -w is specified, the instructional warnings are reported, but other warnings are suppressed.

-x[XCrossFile]

Produces cross-reference output. If you do not specify a file name, a default name is produced by replacing the suffix extension of the source file name with a .xref extension. Conventionally, the suffix is a .s. For example:

sourcefile.xyz

produces a default name of:

sourcefile.xref

Note: The assembler does not generate an object file when the -x flag is used.

-E

Specifies whether to report errors due to the new v2.00 syntax (-Eon), or to ignore them (-Eoff). By default, v2.00 errors are ignored.

-p

Specifies whether to use new v2.00 branch prediction (-pon), or pre-v2.00 branch prediction (-poff). By default, pre-v2.00 branch prediction is used.

-i

Specifies that branch prediction suffixes are to be encoded. By default, this option is not set. This option will be ignored if the -p option is specified.

-v

Displays the version number of this command.

File

Specifies the source file. If no file is specified, the source code is taken from standard input.

Environment Variables

OBJECT_MODE

The assembler respects the setting of the OBJECT_MODE environment variable. If neither -a32 or -a64 is used, the environment is examined for this variable. If the value of the variable is anything other than the values listed in the following table, an error message is generated and the assembler exits with a nonzero return code. The implied behavior corresponding to the valid settings are as follows:

OBJECT_MODE = 32

Produce 32-bit object code. The default machine setting is com.

OBJECT_MODE = 64

Produce 64-bit object code (XCOFF64 files). The default machine setting is ppc64.

OBJECT_MODE = 32_64

Invalid.

OBJECT_MODE = anything else

Invalid.

Examples

1. To produce a listing file named file.lst and an object file named file.o, enter:

   as -l -o file.o file.s

2. To produce an object file named file.o that will run on the 601 processor and generate a cross-reference for POWER family and PowerPC mnemonics in an assembler listing file named file.lst, enter:

   as -s -m 601 -o file.o file.s

3. To produce an object file named file.o using the default assembly mode and an assembler listing file named xxx.lst with no mnemonics cross-reference, enter:

   as -lxxx.lst -o file.o file.s

Files