rchitecture, together with support routines only used by the V850E architecture. `-mv850e2' Specifies that the assembled code should be marked as being targeted at the V850E2 processor. This allows the linker to detect attempts to link such code with code assembled for other processors. `-mv850e2v3' Specifies that the assembled code should be marked as being targeted at the V850E2V3 processor. This allows the linker to detect attempts to link such code with code assembled for other processors. `-mrelax' Enables relaxation. This allows the .longcall and .longjump pseudo ops to be used in the assembler source code. These ops label sections of code which are either a long function call or a long branch. The assembler will then flag these sections of code and the linker will attempt to relax them.  File: as.info, Node: V850 Syntax, Next: V850 Floating Point, Prev: V850 Options, Up: V850-Dependent 9.41.2 Syntax ------------- * Menu: * V850-Chars:: Special Characters * V850-Regs:: Register Names  File: as.info, Node: V850-Chars, Next: V850-Regs, Up: V850 Syntax 9.41.2.1 Special Characters ........................... `#' is the line comment character.  File: as.info, Node: V850-Regs, Prev: V850-Chars, Up: V850 Syntax 9.41.2.2 Register Names ....................... `as' supports the following names for registers: `general register 0' r0, zero `general register 1' r1 `general register 2' r2, hp `general register 3' r3, sp `general register 4' r4, gp `general register 5' r5, tp `general register 6' r6 `general register 7' r7 `general register 8' r8 `general register 9' r9 `general register 10' r10 `general register 11' r11 `general register 12' r12 `general register 13' r13 `general register 14' r14 `general register 15' r15 `general register 16' r16 `general register 17' r17 `general register 18' r18 `general register 19' r19 `general register 20' r20 `general register 21' r21 `general register 22' r22 `general register 23' r23 `general register 24' r24 `general register 25' r25 `general register 26' r26 `general register 27' r27 `general register 28' r28 `general register 29' r29 `general register 30' r30, ep `general register 31' r31, lp `system register 0' eipc `system register 1' eipsw `system register 2' fepc `system register 3' fepsw `system register 4' ecr `system register 5' psw `system register 16' ctpc `system register 17' ctpsw `system register 18' dbpc `system register 19' dbpsw `system register 20' ctbp  File: as.info, Node: V850 Floating Point, Next: V850 Directives, Prev: V850 Syntax, Up: V850-Dependent 9.41.3 Floating Point --------------------- The V850 family uses IEEE floating-point numbers.  File: as.info, Node: V850 Directives, Next: V850 Opcodes, Prev: V850 Floating Point, Up: V850-Dependent 9.41.4 V850 Machine Directives ------------------------------ `.offset ' Moves the offset into the current section to the specified amount. `.section "name", ' This is an extension to the standard .section directive. It sets the current section to be and creates an alias for this section called "name". `.v850' Specifies that the assembled code should be marked as being targeted at the V850 processor. This allows the linker to detect attempts to link such code with code assembled for other processors. `.v850e' Specifies that the assembled code should be marked as being targeted at the V850E processor. This allows the linker to detect attempts to link such code with code assembled for other processors. `.v850e1' Specifies that the assembled code should be marked as being targeted at the V850E1 processor. This allows the linker to detect attempts to link such code with code assembled for other processors. `.v850e2' Specifies that the assembled code should be marked as being targeted at the V850E2 processor. This allows the linker to detect attempts to link such code with code assembled for other processors. `.v850e2v3' Specifies that the assembled code should be marked as being targeted at the V850E2V3 processor. This allows the linker to detect attempts to link such code with code assembled for other processors.  File: as.info, Node: V850 Opcodes, Prev: V850 Directives, Up: V850-Dependent 9.41.5 Opcodes -------------- `as' implements all the standard V850 opcodes. `as' also implements the following pseudo ops: `hi0()' Computes the higher 16 bits of the given expression and stores it into the immediate operand field of the given instruction. For example: `mulhi hi0(here - there), r5, r6' computes the difference between the address of labels 'here' and 'there', takes the upper 16 bits of this difference, shifts it down 16 bits and then multiplies it by the lower 16 bits in register 5, putting the result into register 6. `lo()' Computes the lower 16 bits of the given expression and stores it into the immediate operand field of the given instruction. For example: `addi lo(here - there), r5, r6' computes the difference between the address of labels 'here' and 'there', takes the lower 16 bits of this difference and adds it to register 5, putting the result into register 6. `hi()' Computes the higher 16 bits of the given expression and then adds the value of the most significant bit of the lower 16 bits of the expression and stores the result into the immediate operand field of the given instruction. For example the following code can be used to compute the address of the label 'here' and store it into register 6: `movhi hi(here), r0, r6' `movea lo(here), r6, r6' The reason for this special behaviour is that movea performs a sign extension on its immediate operand. So for example if the address of 'here' was 0xFFFFFFFF then without the special behaviour of the hi() pseudo-op the movhi instruction would put 0xFFFF0000 into r6, then the movea instruction would takes its immediate operand, 0xFFFF, sign extend it to 32 bits, 0xFFFFFFFF, and then add it into r6 giving 0xFFFEFFFF which is wrong (the fifth nibble is E). With the hi() pseudo op adding in the top bit of the lo() pseudo op, the movhi instruction actually stores 0 into r6 (0xFFFF + 1 = 0x0000), so that the movea instruction stores 0xFFFFFFFF into r6 - the right value. `hilo()' Computes the 32 bit value of the given expression and stores it into the immediate operand field of the given instruction (which must be a mov instruction). For example: `mov hilo(here), r6' computes the absolute address of label 'here' and puts the result into register 6. `sdaoff()' Computes the offset of the named variable from the start of the Small Data Area (whoes address is held in register 4, the GP register) and stores the result as a 16 bit signed value in the immediate operand field of the given instruction. For example: `ld.w sdaoff(_a_variable)[gp],r6' loads the contents of the location pointed to by the label '_a_variable' into register 6, provided that the label is located somewhere within +/- 32K of the address held in the GP register. [Note the linker assumes that the GP register contains a fixed address set to the address of the label called '__gp'. This can either be set up automatically by the linker, or specifically set by using the `--defsym __gp=' command line option]. `tdaoff()' Computes the offset of the named variable from the start of the Tiny Data Area (whoes address is held in register 30, the EP register) and stores the result as a 4,5, 7 or 8 bit unsigned value in the immediate operand field of the given instruction. For example: `sld.w tdaoff(_a_variable)[ep],r6' loads the contents of the location pointed to by the label '_a_variable' into register 6, provided that the label is located somewhere within +256 bytes of the address held in the EP register. [Note the linker assumes that the EP register contains a fixed address set to the address of the label called '__ep'. This can either be set up automatically by the linker, or specifically set by using the `--defsym __ep=' command line option]. `zdaoff()' Computes the offset of the named variable from address 0 and stores the result as a 16 bit signed value in the immediate operand field of the given instruction. For example: `movea zdaoff(_a_variable),zero,r6' puts the address of the label '_a_variable' into register 6, assuming that the label is somewhere within the first 32K of memory. (Strictly speaking it also possible to access the last 32K of memory as well, as the offsets are signed). `ctoff()' Computes the offset of the named variable from the start of the Call Table Area (whoes address is helg in system register 20, the CTBP register) and stores the result a 6 or 16 bit unsigned value in the immediate field of then given instruction or piece of data. For example: `callt ctoff(table_func1)' will put the call the function whoes address is held in the call table at the location labeled 'table_func1'. `.longcall `name'' Indicates that the following sequence of instructions is a long call to function `name'. The linker will attempt to shorten this call sequence if `name' is within a 22bit offset of the call. Only valid if the `-mrelax' command line switch has been enabled. `.longjump `name'' Indicates that the following sequence of instructions is a long jump to label `name'. The linker will attempt to shorten this code sequence if `name' is within a 22bit offset of the jump. Only valid if the `-mrelax' command line switch has been enabled. For information on the V850 instruction set, see `V850 Family 32-/16-Bit single-Chip Microcontroller Architecture Manual' from NEC. Ltd.  File: as.info, Node: Xtensa-Dependent, Next: Z80-Dependent, Prev: V850-Dependent, Up: Machine Dependencies 9.42 Xtensa Dependent Features ============================== This chapter covers features of the GNU assembler that are specific to the Xtensa architecture. For details about the Xtensa instruction set, please consult the `Xtensa Instruction Set Architecture (ISA) Reference Manual'. * Menu: * Xtensa Options:: Command-line Options. * Xtensa Syntax:: Assembler Syntax for Xtensa Processors. * Xtensa Optimizations:: Assembler Optimizations. * Xtensa Relaxation:: Other Automatic Transformations. * Xtensa Directives:: Directives for Xtensa Processors.  File: as.info, Node: Xtensa Options, Next: Xtensa Syntax, Up: Xtensa-Dependent 9.42.1 Command Line Options --------------------------- The Xtensa version of the GNU assembler supports these special options: `--text-section-literals | --no-text-section-literals' Control the treatment of literal pools. The default is `--no-text-section-literals', which places literals in separate sections in the output file. This allows the literal pool to be placed in a data RAM/ROM. With `--text-section-literals', the literals are interspersed in the text section in order to keep them as close as possible to their references. This may be necessary for large assembly files, where the literals would otherwise be out of range of the `L32R' instructions in the text section. These options only affect literals referenced via PC-relative `L32R' instructions; literals for absolute mode `L32R' instructions are handled separately. *Note literal: Literal Directive. `--absolute-literals | --no-absolute-literals' Indicate to the assembler whether `L32R' instructions use absolute or PC-relative addressing. If the processor includes the absolute addressing option, the default is to use absolute `L32R' relocations. Otherwise, only the PC-relative `L32R' relocations can be used. `--target-align | --no-target-align' Enable or disable automatic alignment to reduce branch penalties at some expense in code size. *Note Automatic Instruction Alignment: Xtensa Automatic Alignment. This optimization is enabled by default. Note that the assembler will always align instructions like `LOOP' that have fixed alignment requirements. `--longcalls | --no-longcalls' Enable or disable transformation of call instructions to allow calls across a greater range of addresses. *Note Function Call Relaxation: Xtensa Call Relaxation. This option should be used when call targets can potentially be out of range. It may degrade both code size and performance, but the linker can generally optimize away the unnecessary overhead when a call ends up within range. The default is `--no-longcalls'. `--transform | --no-transform' Enable or disable all assembler transformations of Xtensa instructions, including both relaxation and optimization. The default is `--transform'; `--no-transform' should only be used in the rare cases when the instructions must be exactly as specified in the assembly source. Using `--no-transform' causes out of range instruction operands to be errors. `--rename-section OLDNAME=NEWNAME' Rename the OLDNAME section to NEWNAME. This option can be used multiple times to rename multiple sections.  File: as.info, Node: Xtensa Syntax, Next: Xtensa Optimizations, Prev: Xtensa Options, Up: Xtensa-Dependent 9.42.2 Assembler Syntax ----------------------- Block comments are delimited by `/*' and `*/'. End of line comments may be introduced with either `#' or `//'. Instructions consist of a leading opcode or macro name followed by whitespace and an optional comma-separated list of operands: OPCODE [OPERAND, ...] Instructions must be separated by a newline or semicolon. FLIX instructions, which bundle multiple opcodes together in a single instruction, are specified by enclosing the bundled opcodes inside braces: { [FORMAT] OPCODE0 [OPERANDS] OPCODE1 [OPERANDS] OPCODE2 [OPERANDS] ... } The opcodes in a FLIX instruction are listed in the same order as the corresponding instruction slots in the TIE format declaration. Directives and labels are not allowed inside the braces of a FLIX instruction. A particular TIE format name can optionally be specified immediately after the opening brace, but this is usually unnecessary. The assembler will automatically search for a format that can encode the specified opcodes, so the format name need only be specified in rare cases where there is more than one applicable format and where it matters which of those formats is used. A FLIX instruction can also be specified on a single line by separating the opcodes with semicolons: { [FORMAT;] OPCODE0 [OPERANDS]; OPCODE1 [OPERANDS]; OPCODE2 [OPERANDS]; ... } If an opcode can only be encoded in a FLIX instruction but is not specified as part of a FLIX bundle, the assembler will choose the smallest format where the opcode can be encoded and will fill unused instruction slots with no-ops. * Menu: * Xtensa Opcodes:: Opcode Naming Conventions. * Xtensa Registers:: Register Naming.  File: as.info, Node: Xtensa Opcodes, Next: Xtensa Registers, Up: Xtensa Syntax 9.42.2.1 Opcode Names ..................... See the `Xtensa Instruction Set Architecture (ISA) Reference Manual' for a complete list of opcodes and descriptions of their semantics. If an opcode name is prefixed with an underscore character (`_'), `as' will not transform that instruction in any way. The underscore prefix disables both optimization (*note Xtensa Optimizations: Xtensa Optimizations.) and relaxation (*note Xtensa Relaxation: Xtensa Relaxation.) for that particular instruction. Only use the underscore prefix when it is essential to select the exact opcode produced by the assembler. Using this feature unnecessarily makes the code less efficient by disabling assembler optimization and less flexible by disabling relaxation. Note that this special handling of underscore prefixes only applies to Xtensa opcodes, not to either built-in macros or user-defined macros. When an underscore prefix is used with a macro (e.g., `_MOV'), it refers to a different macro. The assembler generally provides built-in macros both with and without the underscore prefix, where the underscore versions behave as if the underscore carries through to the instructions in the macros. For example, `_MOV' may expand to `_MOV.N'. The underscore prefix only applies to individual instructions, not to series of instructions. For example, if a series of instructions have underscore prefixes, the assembler will not transform the individual instructions, but it may insert other instructions between them (e.g., to align a `LOOP' instruction). To prevent the assembler from modifying a series of instructions as a whole, use the `no-transform' directive. *Note transform: Transform Directive.  File: as.info, Node: Xtensa Registers, Prev: Xtensa Opcodes, Up: Xtensa Syntax 9.42.2.2 Register Names ....................... The assembly syntax for a register file entry is the "short" name for a TIE register file followed by the index into that register file. For example, the general-purpose `AR' register file has a short name of `a', so these registers are named `a0'...`a15'. As a special feature, `sp' is also supported as a synonym for `a1'. Additional registers may be added by processor configuration options and by designer-defined TIE extensions. An initial `$' character is optional in all register names.  File: as.info, Node: Xtensa Optimizations, Next: Xtensa Relaxation, Prev: Xtensa Syntax, Up: Xtensa-Dependent 9.42.3 Xtensa Optimizations --------------------------- The optimizations currently supported by `as' are generation of density instructions where appropriate and automatic branch target alignment. * Menu: * Density Instructions:: Using Density Instructions. * Xtensa Automatic Alignment:: Automatic Instruction Alignment.  File: as.info, Node: Density Instructions, Next: Xtensa Automatic Alignment, Up: Xtensa Optimizations 9.42.3.1 Using Density Instructions ................................... The Xtensa instruction set has a code density option that provides 16-bit versions of some of the most commonly used opcodes. Use of these opcodes can significantly reduce code size. When possible, the assembler automatically translates instructions from the core Xtensa instruction set into equivalent instructions from the Xtensa code density option. This translation can be disabled by using underscore prefixes (*note Opcode Names: Xtensa Opcodes.), by using the `--no-transform' command-line option (*note Command Line Options: Xtensa Options.), or by using the `no-transform' directive (*note transform: Transform Directive.). It is a good idea _not_ to use the density instructions directly. The assembler will automatically select dense instructions where possible. If you later need to use an Xtensa processor without the code density option, the same assembly code will then work without modification.  File: as.info, Node: Xtensa Automatic Alignment, Prev: Density Instructions, Up: Xtensa Optimizations 9.42.3.2 Automatic Instruction Alignment ........................................ The Xtensa assembler will automatically align certain instructions, both to optimize performance and to satisfy architectural requirements. As an optimization to improve performance, the assembler attempts to align branch targets so they do not cross instruction fetch boundaries. (Xtensa processors can be configured with either 32-bit or 64-bit instruction fetch widths.) An instruction immediately following a call is treated as a branch target in this context, because it will be the target of a return from the call. This alignment has the potential to reduce branch penalties at some expense in code size. This optimization is enabled by default. You can disable it with the `--no-target-align' command-line option (*note Command Line Options: Xtensa Options.). The target alignment optimization is done without adding instructions that could increase the execution time of the program. If there are density instructions in the code preceding a target, the assembler can change the target alignment by widening some of those instructions to the equivalent 24-bit instructions. Extra bytes of padding can be inserted immediately following unconditional jump and return instructions. This approach is usually successful in aligning many, but not all, branch targets. The `LOOP' family of instructions must be aligned such that the first instruction in the loop body does not cross an instruction fetch boundary (e.g., with a 32-bit fetch width, a `LOOP' instruction must be on either a 1 or 2 mod 4 byte boundary). The assembler knows about this restriction and inserts the minimal number of 2 or 3 byte no-op instructions to satisfy it. When no-op instructions are added, any label immediately preceding the original loop will be moved in order to refer to the loop instruction, not the newly generated no-op instruction. To preserve binary compatibility across processors with different fetch widths, the assembler conservatively assumes a 32-bit fetch width when aligning `LOOP' instructions (except if the first instruction in the loop is a 64-bit instruction). Previous versions of the assembler automatically aligned `ENTRY' instructions to 4-byte boundaries, but that alignment is now the programmer's responsibility.  File: as.info, Node: Xtensa Relaxation, Next: Xtensa Directives, Prev: Xtensa Optimizations, Up: Xtensa-Dependent 9.42.4 Xtensa Relaxation ------------------------ When an instruction operand is outside the range allowed for that particular instruction field, `as' can transform the code to use a functionally-equivalent instruction or sequence of instructions. This process is known as "relaxation". This is typically done for branch instructions because the distance of the branch targets is not known until assembly-time. The Xtensa assembler offers branch relaxation and also extends this concept to function calls, `MOVI' instructions and other instructions with immediate fields. * Menu: * Xtensa Branch Relaxation:: Relaxation of Branches. * Xtensa Call Relaxation:: Relaxation of Function Calls. * Xtensa Immediate Relaxation:: Relaxation of other Immediate Fields.  File: as.info, Node: Xtensa Branch Relaxation, Next: Xtensa Call Relaxation, Up: Xtensa Relaxation 9.42.4.1 Conditional Branch Relaxation ...................................... When the target of a branch is too far away from the branch itself, i.e., when the offset from the branch to the target is too large to fit in the immediate field of the branch instruction, it may be necessary to replace the branch with a branch around a jump. For example, beqz a2, L may result in: bnez.n a2, M j L M: (The `BNEZ.N' instruction would be used in this example only if the density option is available. Otherwise, `BNEZ' would be used.) This relaxation works well because the unconditional jump instruction has a much larger offset range than the various conditional branches. However, an error will occur if a branch target is beyond the range of a jump instruction. `as' cannot relax unconditional jumps. Similarly, an error will occur if the original input contains an unconditional jump to a target that is out of range. Branch relaxation is enabled by default. It can be disabled by using underscore prefixes (*note Opcode Names: Xtensa Opcodes.), the `--no-transform' command-line option (*note Command Line Options: Xtensa Options.), or the `no-transform' directive (*note transform: Transform Directive.).  File: as.info, Node: Xtensa Call Relaxation, Next: Xtensa Immediate Relaxation, Prev: Xtensa Branch Relaxation, Up: Xtensa Relaxation 9.42.4.2 Function Call Relaxation ................................. Function calls may require relaxation because the Xtensa immediate call instructions (`CALL0', `CALL4', `CALL8' and `CALL12') provide a PC-relative offset of only 512 Kbytes in either direction. For larger programs, it may be necessary to use indirect calls (`CALLX0', `CALLX4', `CALLX8' and `CALLX12') where the target address is specified in a register. The Xtensa assembler can automatically relax immediate call instructions into indirect call instructions. This relaxation is done by loading the address of the called function into the callee's return address register and then using a `CALLX' instruction. So, for example: call8 func might be relaxed to: .literal .L1, func l32r a8, .L1 callx8 a8 Because the addresses of targets of function calls are not generally known until link-time, the assembler must assume the worst and relax all the calls to functions in other source files, not just those that really will be out of range. The linker can recognize calls that were unnecessarily relaxed, and it will remove the overhead introduced by the assembler for those cases where direct calls are sufficient. Call relaxation is disabled by default because it can have a negative effect on both code size and performance, although the linker can usually eliminate the unnecessary overhead. If a program is too large and some of the calls are out of range, function call relaxation can be enabled using the `--longcalls' command-line option or the `longcalls' directive (*note longcalls: Longcalls Directive.).  File: as.info, Node: Xtensa Immediate Relaxation, Prev: Xtensa Call Relaxation, Up: Xtensa Relaxation 9.42.4.3 Other Immediate Field Relaxation ......................................... The assembler normally performs the following other relaxations. They can be disabled by using underscore prefixes (*note Opcode Names: Xtensa Opcodes.), the `--no-transform' command-line option (*note Command Line Options: Xtensa Options.), or the `no-transform' directive (*note transform: Transform Directive.). The `MOVI' machine instruction can only materialize values in the range from -2048 to 2047. Values outside this range are best materialized with `L32R' instructions. Thus: movi a0, 100000 is assembled into the following machine code: .literal .L1, 100000 l32r a0, .L1 The `L8UI' machine instruction can only be used with immediate offsets in the range from 0 to 255. The `L16SI' and `L16UI' machine instructions can only be used with offsets from 0 to 510. The `L32I' machine instruction can only be used with offsets from 0 to 1020. A load offset outside these ranges can be materialized with an `L32R' instruction if the destination register of the load is different than the source address register. For example: l32i a1, a0, 2040 is translated to: .literal .L1, 2040 l32r a1, .L1 add a1, a0, a1 l32i a1, a1, 0 If the load destination and source address register are the same, an out-of-range offset causes an error. The Xtensa `ADDI' instruction only allows immediate operands in the range from -128 to 127. There are a number of alternate instruction sequences for the `ADDI' operation. First, if the immediate is 0, the `ADDI' will be turned into a `MOV.N' instruction (or the equivalent `OR' instruction if the code density option is not available). If the `ADDI' immediate is outside of the range -128 to 127, but inside the range -32896 to 32639, an `ADDMI' instruction or `ADDMI'/`ADDI' sequence will be used. Finally, if the immediate is outside of this range and a free register is available, an `L32R'/`ADD' sequence will be used with a literal allocated from the literal pool. For example: addi a5, a6, 0 addi a5, a6, 512 addi a5, a6, 513 addi a5, a6, 50000 is assembled into the following: .literal .L1, 50000 mov.n a5, a6 addmi a5, a6, 0x200 addmi a5, a6, 0x200 addi a5, a5, 1 l32r a5, .L1 add a5, a6, a5  File: as.info, Node: Xtensa Directives, Prev: Xtensa Relaxation, Up: Xtensa-Dependent 9.42.5 Directives ----------------- The Xtensa assembler supports a region-based directive syntax: .begin DIRECTIVE [OPTIONS] ... .end DIRECTIVE All the Xtensa-specific directives that apply to a region of code use this syntax. The directive applies to code between the `.begin' and the `.end'. The state of the option after the `.end' reverts to what it was before the `.begin'. A nested `.begin'/`.end' region can further change the state of the directive without having to be aware of its outer state. For example, consider: .begin no-transform L: add a0, a1, a2 .begin transform M: add a0, a1, a2 .end transform N: add a0, a1, a2 .end no-transform The `ADD' opcodes at `L' and `N' in the outer `no-transform' region both result in `ADD' machine instructions, but the assembler selects an `ADD.N' instruction for the `ADD' at `M' in the inner `transform' region. The advantage of this style is that it works well inside macros which can preserve the context of their callers. The following directives are available: * Menu: * Schedule Directive:: Enable instruction scheduling. * Longcalls Directive:: Use Indirect Calls for Greater Range. * Transform Directive:: Disable All Assembler Transformations. * Literal Directive:: Intermix Literals with Instructions. * Literal Position Directive:: Specify Inline Literal Pool Locations. * Literal Prefix Directive:: Specify Literal Section Name Prefix. * Absolute Literals Directive:: Control PC-Relative vs. Absolute Literals.  File: as.info, Node: Schedule Directive, Next: Longcalls Directive, Up: Xtensa Directives 9.42.5.1 schedule ................. The `schedule' directive is recognized only for compatibility with Tensilica's assembler. .begin [no-]schedule .end [no-]schedule This directive is ignored and has no effect on `as'.  File: as.info, Node: Longcalls Directive, Next: Transform Directive, Prev: Schedule Directive, Up: Xtensa Directives 9.42.5.2 longcalls .................. The `longcalls' directive enables or disables function call relaxation. *Note Function Call Relaxation: Xtensa Call Relaxation. .begin [no-]longcalls .end [no-]longcalls Call relaxation is disabled by default unless the `--longcalls' command-line option is specified. The `longcalls' directive overrides the default determined by the command-line options.  File: as.info, Node: Transform Directive, Next: Literal Directive, Prev: Longcalls Directive, Up: Xtensa Directives 9.42.5.3 transform .................. This directive enables or disables all assembler transformation, including relaxation (*note Xtensa Relaxation: Xtensa Relaxation.) and optimization (*note Xtensa Optimizations: Xtensa Optimizations.). .begin [no-]transform .end [no-]transform Transformations are enabled by default unless the `--no-transform' option is used. The `transform' directive overrides the default determined by the command-line options. An underscore opcode prefix, disabling transformation of that opcode, always takes precedence over both directives and command-line flags.  File: as.info, Node: Literal Directive, Next: Literal Position Directive, Prev: Transform Directive, Up: Xtensa Directives 9.42.5.4 literal ................ The `.literal' directive is used to define literal pool data, i.e., read-only 32-bit data accessed via `L32R' instructions. .literal LABEL, VALUE[, VALUE...] This directive is similar to the standard `.word' directive, except that the actual location of the literal data is determined by the assembler and linker, not by the position of the `.literal' directive. Using this directive gives the assembler freedom to locate the literal data in the most appropriate place and possibly to combine identical literals. For example, the code: entry sp, 40 .literal .L1, sym l32r a4, .L1 can be used to load a pointer to the symbol `sym' into register `a4'. The value of `sym' will not be placed between the `ENTRY' and `L32R' instructions; instead, the assembler puts the data in a literal pool. Literal pools are placed by default in separate literal sections; however, when using the `--text-section-literals' option (*note Command Line Options: Xtensa Options.), the literal pools for PC-relative mode `L32R' instructions are placed in the current section.(1) These text section literal pools are created automatically before `ENTRY' instructions and manually after `.literal_position' directives (*note literal_position: Literal Position Directive.). If there are no preceding `ENTRY' instructions, explicit `.literal_position' directives must be used to place the text section literal pools; otherwise, `as' will report an error. When literals are placed in separate sections, the literal section names are derived from the names of the sections where the literals are defined. The base literal section names are `.literal' for PC-relative mode `L32R' instructions and `.lit4' for absolute mode `L32R' instructions (*note absolute-literals: Absolute Literals Directive.). These base names are used for literals defined in the default `.text' section. For literals defined in other sections or within the scope of a `literal_prefix' directive (*note literal_prefix: Literal Prefix Directive.), the following rules determine the literal section name: 1. If the current section is a member of a section group, the literal section name includes the group name as a suffix to the base `.literal' or `.lit4' name, with a period to separate the base name and group name. The literal section is also made a member of the group. 2. If the current section name (or `literal_prefix' value) begins with "`.gnu.linkonce.KIND.'", the literal section name is formed by replacing "`.KIND'" with the base `.literal' or `.lit4' name. For example, for literals defined in a section named `.gnu.linkonce.t.func', the literal section will be `.gnu.linkonce.literal.func' or `.gnu.linkonce.lit4.func'. 3. If the current section name (or `literal_prefix' value) ends with `.text', the literal section name is formed by replacing that suffix with the base `.literal' or `.lit4' name. For example, for literals defined in a section named `.iram0.text', the literal section will be `.iram0.literal' or `.iram0.lit4'. 4. If none of the preceding conditions apply, the literal section name is formed by adding the base `.literal' or `.lit4' name as a suffix to the current section name (or `literal_prefix' value). ---------- Footnotes ---------- (1) Literals for the `.init' and `.fini' sections are always placed in separate sections, even when `--text-section-literals' is enabled.  File: as.info, Node: Literal Position Directive, Next: Literal Prefix Directive, Prev: Literal Directive, Up: Xtensa Directives 9.42.5.5 literal_position ......................... When using `--text-section-literals' to place literals inline in the section being assembled, the `.literal_position' directive can be used to mark a potential location for a literal pool. .literal_position The `.literal_position' directive is ignored when the `--text-section-literals' option is not used or when `L32R' instructions use the absolute addressing mode. The assembler will automatically place text section literal pools before `ENTRY' instructions, so the `.literal_position' directive is only needed to specify some other location for a literal pool. You may need to add an explicit jump instruction to skip over an inline literal pool. For example, an interrupt vector does not begin with an `ENTRY' instruction so the assembler will be unable to automatically find a good place to put a literal pool. Moreover, the code for the interrupt vector must be at a specific starting address, so the literal pool cannot come before the start of the code. The literal pool for the vector must be explicitly positioned in the middle of the vector (before any uses of the literals, due to the negative offsets used by PC-relative `L32R' instructions). The `.literal_position' directive can be used to do this. In the following code, the literal for `M' will automatically be aligned correctly and is placed after the unconditional jump. .global M code_start: j continue .literal_position .align 4 continue: movi a4, M  File: as.info, Node: Literal Prefix Directive, Next: Absolute Literals Directive, Prev: Literal Position Directive, Up: Xtensa Directives 9.42.5.6 literal_prefix ....................... The `literal_prefix' directive allows you to override the default literal section names, which are derived from the names of the sections where the literals are defined. .begin literal_prefix [NAME] .end literal_prefix For literals defined within the delimited region, the literal section names are derived from the NAME argument instead of the name of the current section. The rules used to derive the literal section names do not change. *Note literal: Literal Directive. If the NAME argument is omitted, the literal sections revert to the defaults. This directive has no effect when using the `--text-section-literals' option (*note Command Line Options: Xtensa Options.).  File: as.info, Node: Absolute Literals Directive, Prev: Literal Prefix Directive, Up: Xtensa Directives 9.42.5.7 absolute-literals .......................... The `absolute-literals' and `no-absolute-literals' directives control the absolute vs. PC-relative mode for `L32R' instructions. These are relevant only for Xtensa configurations that include the absolute addressing option for `L32R' instructions. .begin [no-]absolute-literals .end [no-]absolute-literals These directives do not change the `L32R' mode--they only cause the assembler to emit the appropriate kind of relocation for `L32R' instructions and to place the literal values in the appropriate section. To change the `L32R' mode, the program must write the `LITBASE' special register. It is the programmer's responsibility to keep track of the mode and indicate to the assembler which mode is used in each region of code. If the Xtensa configuration includes the absolute `L32R' addressing option, the default is to assume absolute `L32R' addressing unless the `--no-absolute-literals' command-line option is specified. Otherwise, the default is to assume PC-relative `L32R' addressing. The `absolute-literals' directive can then be used to override the default determined by the command-line options.  File: as.info, Node: Reporting Bugs, Next: Acknowledgements, Prev: Machine Dependencies, Up: Top 10 Reporting Bugs ***************** Your bug reports play an essential role in making `as' reliable. Reporting a bug may help you by bringing a solution to your problem, or it may not. But in any case the principal function of a bug report is to help the entire community by making the next version of `as' work better. Bug reports are your contribution to the maintenance of `as'. In order for a bug report to serve its purpose, you must include the information that enables us to fix the bug. * Menu: * Bug Criteria:: Have you found a bug? * Bug Reporting:: How to report bugs  File: as.info, Node: Bug Criteria, Next: Bug Reporting, Up: Reporting Bugs 10.1 Have You Found a Bug? ========================== If you are not sure whether you have found a bug, here are some guidelines: * If the assembler gets a fatal signal, for any input whatever, that is a `as' bug. Reliable assemblers never crash. * If `as' produces an error message for valid input, that is a bug. * If `as' does not produce an error message for invalid input, that is a bug. However, you should note that your idea of "invalid input" might be our idea of "an extension" or "support for traditional practice". * If you are an experienced user of assemblers, your suggestions for improvement of `as' are welcome in any case.  File: as.info, Node: Bug Reporting, Prev: Bug Criteria, Up: Reporting Bugs 10.2 How to Report Bugs ======================= A number of companies and individuals offer support for GNU products. If you obtained `as' from a support organization, we recommend you contact that organization first. You can find contact information for many support companies and individuals in the file `etc/SERVICE' in the GNU Emacs distribution. In any event, we also recommend that you send bug reports for `as' to `http://www.sourceware.org/bugzilla/'. The fundamental principle of reporting bugs usefully is this: *report all the facts*. If you are not sure whether to state a fact or leave it out, state it! Often people omit facts because they think they know what causes the problem and assume that some details do not matter. Thus, you might assume that the name of a symbol you use in an example does not matter. Well, probably it does not, but one cannot be sure. Perhaps the bug is a stray memory reference which happens to fetch from the location where that name is stored in memory; perhaps, if the name were different, the contents of that location would fool the assembler into doing the right thing despite the bug. Play it safe and give a specific, complete example. That is the easiest thing for you to do, and the most helpful. Keep in mind that the purpose of a bug report is to enable us to fix the bug if it is new to us. Therefore, always write your bug reports on the assumption that the bug has not been reported previously. Sometimes people give a few sketchy facts and ask, "Does this ring a bell?" This cannot help us fix a bug, so it is basically useless. We respond by asking for enough details to enable us to investigate. You might as well expedite matters by sending them to begin with. To enable us to fix the bug, you should include all these things: * The version of `as'. `as' announces it if you start it with the `--version' argument. Without this, we will not know whether there is any point in looking for the bug in the current version of `as'. * Any patches you may have applied to the `as' source. * The type of machine you are using, and the operating system name and version number. * What compiler (and its version) was used to compile `as'--e.g. "`gcc-2.7'". * The command arguments you gave the assembler to assemble your example and observe the bug. To guarantee you will not omit something important, list them all. A copy of the Makefile (or the output from make) is sufficient. If we were to try to guess the arguments, we would probably guess wrong and then we might not encounter the bug. * A complete input file that will reproduce the bug. If the bug is observed when the assembler is invoked via a compiler, send the assembler source, not the high level language source. Most compilers will produce the assembler source when run with the `-S' option. If you are using `gcc', use the options `-v --save-temps'; this will save the assembler source in a file with an extension of `.s', and also show you exactly how `as' is being run. * A description of what behavior you observe that you believe is incorrect. For example, "It gets a fatal signal." Of course, if the bug is that `as' gets a fatal signal, then we will certainly notice it. But if the bug is incorrect output, we might not notice unless it is glaringly wrong. You might as well not give us a chance to make a mistake. Even if the problem you experience is a fatal signal, you should still say so explicitly. Suppose something strange is going on, such as, your copy of `as' is out of sync, or you have encountered a bug in the C library on your system. (This has happened!) Your copy might crash and ours would not. If you told us to expect a crash, then when ours fails to crash, we would know that the bug was not happening for us. If you had not told us to expect a crash, then we would not be able to draw any conclusion from our observations. * If you wish to suggest changes to the `as' source, send us context diffs, as generated by `diff' with the `-u', `-c', or `-p' option. Always send diffs from the old file to the new file. If you even discuss something in the `as' source, refer to it by context, not by line number. The line numbers in our development sources will not match those in your sources. Your line numbers would convey no useful information to us. Here are some things that are not necessary: * A description of the envelope of the bug. Often people who encounter a bug spend a lot of time investigating which changes to the input file will make the bug go away and which changes will not affect it. This is often time consuming and not very useful, because the way we will find the bug is by running a single example under the debugger with breakpoints, not by pure deduction from a series of examples. We recommend that you save your time for something else. Of course, if you can find a simpler example to report _instead_ of the original one, that is a convenience for us. Errors in the output will be easier to spot, running under the debugger will take less time, and so on. However, simplification is not vital; if you do not want to do this, report the bug anyway and send us the entire test case you used. * A patch for the bug. A patch for the bug does help us if it is a good one. But do not omit the necessary information, such as the test case, on the assumption that a patch is all we need. We might see problems with your patch and decide to fix the problem another way, or we might not understand it at all. Sometimes with a program as complicated as `as' it is very hard to construct an example that will make the program follow a certain path through the code. If you do not send us the example, we will not be able to construct one, so we will not be able to verify that the bug is fixed. And if we cannot understand what bug you are trying to fix, or why your patch should be an improvement, we will not install it. A test case will help us to understand. * A guess about what the bug is or what it depends on. Such guesses are usually wrong. Even we cannot guess right about such things without first using the debugger to find the facts.  File: as.info, Node: Acknowledgements, Next: GNU Free Documentation License, Prev: Reporting Bugs, Up: Top 11 Acknowledgements ******************* If you have contributed to GAS and your name isn't listed here, it is not meant as a slight. We just don't know about it. Send mail to the maintainer, and we'll correct the situation. Currently the maintainer is Ken Raeburn (email address `raeburn@cygnus.com'). Dean Elsner wrote the original GNU assembler for the VAX.(1) Jay Fenlason maintained GAS for a while, adding support for GDB-specific debug information and the 68k series machines, most of the preprocessing pass, and extensive changes in `messages.c', `input-file.c', `write.c'. K. Richard Pixley maintained GAS for a while, adding various enhancements and many bug fixes, including merging support for several processors, breaking GAS up to handle multiple object file format back ends (including heavy rewrite, testing, an integration of the coff and b.out back ends), adding configuration including heavy testing and verification of cross assemblers and file splits and renaming, converted GAS to strictly ANSI C including full prototypes, added support for m680[34]0 and cpu32, did considerable work on i960 including a COFF port (including considerable amounts of reverse engineering), a SPARC opcode file rewrite, DECstation, rs6000, and hp300hpux host ports, updated "know" assertions and made them work, much other reorganization, cleanup, and lint. Ken Raeburn wrote the high-level BFD interface code to replace most of the code in format-specific I/O modules. The original VMS support was contributed by David L. Kashtan. Eric Youngdale has done much work with it since. The Intel 80386 machine description was written by Eliot Dresselhaus. Minh Tran-Le at IntelliCorp contributed some AIX 386 support. The Motorola 88k machine description was contributed by Devon Bowen of Buffalo University and Torbjorn Granlund of the Swedish Institute of Computer Science. Keith Knowles at the Open Software Foundation wrote the original MIPS back end (`tc-mips.c', `tc-mips.h'), and contributed Rose format support (which hasn't been merged in yet). Ralph Campbell worked with the MIPS code to support a.out format. Support for the Zilog Z8k and Renesas H8/300 processors (tc-z8k, tc-h8300), and IEEE 695 object file format (obj-ieee), was written by Steve Chamberlain of Cygnus Support. Steve also modified the COFF back end to use BFD for some low-level operations, for use with the H8/300 and AMD 29k targets. John Gilmore built the AMD 29000 support, added `.include' support, and simplified the configuration of which versions accept which directives. He updated the 68k machine description so that Motorola's opcodes always produced fixed-size instructions (e.g., `jsr'), while synthetic instructions remained shrinkable (`jbsr'). John fixed many bugs, including true tested cross-compilation support, and one bug in relaxation that took a week and required the proverbial one-bit fix. Ian Lance Taylor of Cygnus Support merged the Motorola and MIT syntax for the 68k, completed support for some COFF targets (68k, i386 SVR3, and SCO Unix), added support for MIPS ECOFF and ELF targets, wrote the initial RS/6000 and PowerPC assembler, and made a few other minor patches. Steve Chamberlain made GAS able to generate listings. Hewlett-Packard contributed support for the HP9000/300. Jeff Law wrote GAS and BFD support for the native HPPA object format (SOM) along with a fairly extensive HPPA testsuite (for both SOM and ELF object formats). This work was supported by both the Center for Software Science at the University of Utah and Cygnus Support. Support for ELF format files has been worked on by Mark Eichin of Cygnus Support (original, incomplete implementation for SPARC), Pete Hoogenboom and Jeff Law at the University of Utah (HPPA mainly), Michael Meissner of the Open Software Foundation (i386 mainly), and Ken Raeburn of Cygnus Support (sparc, and some initial 64-bit support). Linas Vepstas added GAS support for the ESA/390 "IBM 370" architecture. Richard Henderson rewrote the Alpha assembler. Klaus Kaempf wrote GAS and BFD support for openVMS/Alpha. Timothy Wall, Michael Hayes, and Greg Smart contributed to the various tic* flavors. David Heine, Sterling Augustine, Bob Wilson and John Ruttenberg from Tensilica, Inc. added support for Xtensa processors. Several engineers at Cygnus Support have also provided many small bug fixes and configuration enhancements. Jon Beniston added support for the Lattice Mico32 architecture. Many others have contributed large or small bugfixes and enhancements. If you have contributed significant work and are not mentioned on this list, and want to be, let us know. Some of the history has been lost; we are not intentionally leaving anyone out. ---------- Footnotes ---------- (1) Any more details?  File: as.info, Node: GNU Free Documentation License, Next: AS Index, Prev: Acknowledgements, Up: Top Appendix A GNU Free Documentation License ***************************************** Version 1.3, 3 November 2008 Copyright (C) 2000, 2001, 2002, 2007, 2008 Free Software Foundation, Inc. `http://fsf.org/' Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed. 0. PREAMBLE The purpose of this License is to make a manual, textbook, or other functional and useful document "free" in the sense of freedom: to assure everyone the effective freedom to copy and redistribute it, with or without modifying it, either commercially or noncommercially. Secondarily, this License preserves for the author and publisher a way to get credit for their work, while not being considered responsible for modifications made by others. This License is a kind of "copyleft", which means that derivative works of the document must themselves be free in the same sense. It complements the GNU General Public License, which is a copyleft license designed for free software. We have designed this License in order to use it for manuals for free software, because free software needs free documentation: a free program should come with manuals providing the same freedoms that the software does. But this License is not limited to software manuals; it can be used for any textual work, regardless of subject matter or whether it is published as a printed book. We recommend this License principally for works whose purpose is instruction or reference. 1. APPLICABILITY AND DEFINITIONS This License applies to any manual or other work, in any medium, that contains a notice placed by the copyright holder saying it can be distributed under the terms of this License. Such a notice grants a world-wide, royalty-free license, unlimited in duration, to use that work under the conditions stated herein. The "Document", below, refers to any such manual or work. Any member of the public is a licensee, and is addressed as "you". You accept the license if you copy, modify or distribute the work in a way requiring permission under copyright law. A "Modified Version" of the Document means any work containing the Document or a portion of it, either copied verbatim, or with modifications and/or translated into another language. A "Secondary Section" is a named appendix or a front-matter section of the Document that deals exclusively with the relationship of the publishers or authors of the Document to the Document's overall subject (or to related matters) and contains nothing that could fall directly within that overall subject. (Thus, if the Document is in part a textbook of mathematics, a Secondary Section may not explain any mathematics.) The relationship could be a matter of historical connection with the subject or with related matters, or of legal, commercial, philosophical, ethical or political position regarding them. The "Invariant Sections" are certain Secondary Sections whose titles are designated, as being those of Invariant Sections, in the notice that says that the Document is released under this License. If a section does not fit the above definition of Secondary then it is not allowed to be designated as Invariant. The Document may contain zero Invariant Sections. If the Document does not identify any Invariant Sections then there are none. The "Cover Texts" are certain short passages of text that are listed, as Front-Cover Texts or Back-Cover Texts, in the notice that says that the Document is released under this License. A Front-Cover Text may be at most 5 words, and a Back-Cover Text may be at most 25 words. A "Transparent" copy of the Document means a machine-readable copy, represented in a format whose specification is available to the general public, that is suitable for revising the document straightforwardly with generic text editors or (for images composed of pixels) generic paint programs or (for drawings) some widely available drawing editor, and that is suitable for input to text formatters or for automatic translation to a variety of formats suitable for input to text formatters. A copy made in an otherwise Transparent file format whose markup, or absence of markup, has been arranged to thwart or discourage subsequent modification by readers is not Transparent. An image format is not Transparent if used for any substantial amount of text. A copy that is not "Transparent" is called "Opaque". Examples of suitable formats for Transparent copies include plain ASCII without markup, Texinfo input format, LaTeX input format, SGML or XML using a publicly available DTD, and standard-conforming simple HTML, PostScript or PDF designed for human modification. Examples of transparent image formats include PNG, XCF and JPG. Opaque formats include proprietary formats that can be read and edited only by proprietary word processors, SGML or XML for which the DTD and/or processing tools are not generally available, and the machine-generated HTML, PostScript or PDF produced by some word processors for output purposes only. The "Title Page" means, for a printed book, the title page itself, plus such following pages as are needed to hold, legibly, the material this License requires to appear in the title page. For works in formats which do not have any title page as such, "Title Page" means the text near the most prominent appearance of the work's title, preceding the beginning of the body of the text. The "publisher" means any person or entity that distributes copies of the Document to the public. A section "Entitled XYZ" means a named subunit of the Document whose title either is precisely XYZ or contains XYZ in parentheses following text that translates XYZ in another language. (Here XYZ stands for a specific section name mentioned below, such as "Acknowledgements", "Dedications", "Endorsements", or "History".) To "Preserve the Title" of such a section when you modify the Document means that it remains a section "Entitled XYZ" according to this definition. The Document may include Warranty Disclaimers next to the notice which states that this License applies to the Document. These Warranty Disclaimers are considered to be included by reference in this License, but only as regards disclaiming warranties: any other implication that these Warranty Disclaimers may have is void and has no effect on the meaning of this License. 2. VERBATIM COPYING You may copy and distribute the Document in any medium, either commercially or noncommercially, provided that this License, the copyright notices, and the license notice saying this License applies to the Document are reproduced in all copies, and that you add no other conditions whatsoever to those of this License. You may not use technical measures to obstruct or control the reading or further copying of the copies you make or distribute. However, you may accept compensation in exchange for copies. If you distribute a large enough number of copies you must also follow the conditions in section 3. You may also lend copies, under the same conditions stated above, and you may publicly display copies. 3. COPYING IN QUANTITY If you publish printed copies (or copies in media that commonly have printed covers) of the Document, numbering more than 100, and the Document's license notice requires Cover Texts, you must enclose the copies in covers that carry, clearly and legibly, all these Cover Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on the back cover. Both covers must also clearly and legibly identify you as the publisher of these copies. The front cover must present the full title with all words of the title equally prominent and visible. You may add other material on the covers in addition. Copying with changes limited to the covers, as long as they preserve the title of the Document and satisfy these conditions, can be treated as verbatim copying in other respects. If the required texts for either cover are too voluminous to fit legibly, you should put the first ones listed (as many as fit reasonably) on the actual cover, and continue the rest onto adjacent pages. If you publish or distribute Opaque copies of the Document numbering more than 100, you must either include a machine-readable Transparent copy along with each Opaque copy, or state in or with each Opaque copy a computer-network location from which the general network-using public has access to download using public-standard network protocols a complete Transparent copy of the Document, free of added material. If you use the latter option, you must take reasonably prudent steps, when you begin distribution of Opaque copies in quantity, to ensure that this Transparent copy will remain thus accessible at the stated location until at least one year after the last time you distribute an Opaque copy (directly or through your agents or retailers) of that edition to the public. It is requested, but not required, that you contact the authors of the Document well before redistributing any large number of copies, to give them a chance to provide you with an updated version of the Document. 4. MODIFICATIONS You may copy and distribute a Modified Version of the Document under the conditions of sections 2 and 3 above, provided that you release the Modified Version under precisely this License, with the Modified Version filling the role of the Document, thus licensing distribution and modification of the Modified Version to whoever possesses a copy of it. In addition, you must do these things in the Modified Version: A. Use in the Title Page (and on the covers, if any) a title distinct from that of the Document, and from those of previous versions (which should, if there were any, be listed in the History section of the Document). You may use the same title as a previous version if the original publisher of that version gives permission. B. List on the Title Page, as authors, one or more persons or entities responsible for authorship of the modifications in the Modified Version, together with at least five of the principal authors of the Document (all of its principal authors, if it has fewer than five), unless they release you from this requirement. C. State on the Title page the name of the publisher of the Modified Version, as the publisher. D. Preserve all the copyright notices of the Document. E. Add an appropriate copyright notice for your modifications adjacent to the other copyright notices. F. Include, immediately after the copyright notices, a license notice giving the public permission to use the Modified Version under the terms of this License, in the form shown in the Addendum below. G. Preserve in that license notice the full lists of Invariant Sections and required Cover Texts given in the Document's license notice. H. Include an unaltered copy of this License. I. Preserve the section Entitled "History", Preserve its Title, and add to it an item stating at least the title, year, new authors, and publisher of the Modified Version as given on the Title Page. If there is no section Entitled "History" in the Document, create one stating the title, year, authors, and publisher of the Document as given on its Title Page,