1@c Copyright (C) 2002 Free Software Foundation, Inc. 2@c This is part of the GAS manual. 3@c For copying conditions, see the file as.texinfo. 4@c 5@ifset GENERIC 6@page 7@node Xtensa-Dependent 8@chapter Xtensa Dependent Features 9@end ifset 10@ifclear GENERIC 11@node Machine Dependencies 12@chapter Xtensa Dependent Features 13@end ifclear 14 15@cindex Xtensa architecture 16This chapter covers features of the @sc{gnu} assembler that are specific 17to the Xtensa architecture. For details about the Xtensa instruction 18set, please consult the @cite{Xtensa Instruction Set Architecture (ISA) 19Reference Manual}. 20 21@menu 22* Xtensa Options:: Command-line Options. 23* Xtensa Syntax:: Assembler Syntax for Xtensa Processors. 24* Xtensa Optimizations:: Assembler Optimizations. 25* Xtensa Relaxation:: Other Automatic Transformations. 26* Xtensa Directives:: Directives for Xtensa Processors. 27@end menu 28 29@node Xtensa Options 30@section Command Line Options 31 32The Xtensa version of the @sc{gnu} assembler supports these 33special options: 34 35@table @code 36@item --density | --no-density 37@kindex --density 38@kindex --no-density 39@cindex Xtensa density option 40@cindex density option, Xtensa 41Enable or disable use of the Xtensa code density option (16-bit 42instructions). @xref{Density Instructions, ,Using Density 43Instructions}. If the processor is configured with the density option, 44this is enabled by default; otherwise, it is always disabled. 45 46@item --relax | --no-relax 47@kindex --relax 48@kindex --no-relax 49Enable or disable relaxation of instructions with immediate operands 50that are outside the legal range for the instructions. @xref{Xtensa 51Relaxation, ,Xtensa Relaxation}. The default is @samp{--relax} and this 52default should almost always be used. If relaxation is disabled with 53@samp{--no-relax}, instruction operands that are out of range will cause 54errors. Note: In the current implementation, these options also control 55whether assembler optimizations are performed, making these options 56equivalent to @samp{--generics} and @samp{--no-generics}. 57 58@item --generics | --no-generics 59@kindex --generics 60@kindex --no-generics 61Enable or disable all assembler transformations of Xtensa instructions, 62including both relaxation and optimization. The default is 63@samp{--generics}; @samp{--no-generics} should only be used in the rare 64cases when the instructions must be exactly as specified in the assembly 65source. 66@c The @samp{--no-generics} option is like @samp{--no-relax} 67@c except that it also disables assembler optimizations (@pxref{Xtensa 68@c Optimizations}). 69As with @samp{--no-relax}, using @samp{--no-generics} 70causes out of range instruction operands to be errors. 71 72@item --text-section-literals | --no-text-section-literals 73@kindex --text-section-literals 74@kindex --no-text-section-literals 75Control the treatment of literal pools. The default is 76@samp{--no-@-text-@-section-@-literals}, which places literals in a 77separate section in the output file. This allows the literal pool to be 78placed in a data RAM/ROM, and it also allows the linker to combine literal 79pools from separate object files to remove redundant literals and 80improve code size. With @samp{--text-@-section-@-literals}, the 81literals are interspersed in the text section in order to keep them as 82close as possible to their references. This may be necessary for large 83assembly files. 84 85@item --target-align | --no-target-align 86@kindex --target-align 87@kindex --no-target-align 88Enable or disable automatic alignment to reduce branch penalties at some 89expense in code size. @xref{Xtensa Automatic Alignment, ,Automatic 90Instruction Alignment}. This optimization is enabled by default. Note 91that the assembler will always align instructions like @code{LOOP} that 92have fixed alignment requirements. 93 94@item --longcalls | --no-longcalls 95@kindex --longcalls 96@kindex --no-longcalls 97Enable or disable transformation of call instructions to allow calls 98across a greater range of addresses. @xref{Xtensa Call Relaxation, 99,Function Call Relaxation}. This option should be used when call 100targets can potentially be out of range, but it degrades both code size 101and performance. The default is @samp{--no-@-longcalls}. 102@end table 103 104@node Xtensa Syntax 105@section Assembler Syntax 106@cindex syntax, Xtensa assembler 107@cindex Xtensa assembler syntax 108 109Block comments are delimited by @samp{/*} and @samp{*/}. End of line 110comments may be introduced with either @samp{#} or @samp{//}. 111 112Instructions consist of a leading opcode or macro name followed by 113whitespace and an optional comma-separated list of operands: 114 115@smallexample 116@var{opcode} [@var{operand},@dots{}] 117@end smallexample 118 119Instructions must be separated by a newline or semicolon. 120 121@menu 122* Xtensa Opcodes:: Opcode Naming Conventions. 123* Xtensa Registers:: Register Naming. 124@end menu 125 126@node Xtensa Opcodes 127@subsection Opcode Names 128@cindex Xtensa opcode names 129@cindex opcode names, Xtenxa 130 131See the @cite{Xtensa Instruction Set Architecture (ISA) Reference 132Manual} for a complete list of opcodes and descriptions of their 133semantics. 134 135@cindex generic opcodes 136@cindex specific opcodes 137@cindex _ opcode prefix 138The Xtensa assembler distinguishes between @dfn{generic} and 139@dfn{specific} opcodes. Specific opcodes correspond directly to Xtensa 140machine instructions. Prefixing an opcode with an underscore character 141(@samp{_}) identifies it as a specific opcode. Opcodes without a 142leading underscore are generic, which means the assembler is required to 143preserve their semantics but may not translate them directly to the 144specific opcodes with the same names. Instead, the assembler may 145optimize a generic opcode and select a better instruction to use in its 146place (@pxref{Xtensa Optimizations, ,Xtensa Optimizations}), or the 147assembler may relax the instruction to handle operands that are out of 148range for the corresponding specific opcode (@pxref{Xtensa Relaxation, 149,Xtensa Relaxation}). 150 151Only use specific opcodes when it is essential to select 152the exact machine instructions produced by the assembler. 153Using specific opcodes unnecessarily only makes the code less 154efficient, by disabling assembler optimization, and less flexible, by 155disabling relaxation. 156 157Note that this special handling of underscore prefixes only applies to 158Xtensa opcodes, not to either built-in macros or user-defined macros. 159When an underscore prefix is used with a macro (e.g., @code{_NOP}), it 160refers to a different macro. The assembler generally provides built-in 161macros both with and without the underscore prefix, where the underscore 162versions behave as if the underscore carries through to the instructions 163in the macros. For example, @code{_NOP} expands to @code{_OR a1,a1,a1}. 164 165The underscore prefix only applies to individual instructions, not to 166series of instructions. For example, if a series of instructions have 167underscore prefixes, the assembler will not transform the individual 168instructions, but it may insert other instructions between them (e.g., 169to align a @code{LOOP} instruction). To prevent the assembler from 170modifying a series of instructions as a whole, use the 171@code{no-generics} directive. @xref{Generics Directive, ,generics}. 172 173@node Xtensa Registers 174@subsection Register Names 175@cindex Xtensa register names 176@cindex register names, Xtensa 177@cindex sp register 178 179An initial @samp{$} character is optional in all register names. 180General purpose registers are named @samp{a0}@dots{}@samp{a15}. Additional 181registers may be added by processor configuration options. In 182particular, the @sc{mac16} option adds a @sc{mr} register bank. Its 183registers are named @samp{m0}@dots{}@samp{m3}. 184 185As a special feature, @samp{sp} is also supported as a synonym for 186@samp{a1}. 187 188@node Xtensa Optimizations 189@section Xtensa Optimizations 190@cindex optimizations 191 192The optimizations currently supported by @code{@value{AS}} are 193generation of density instructions where appropriate and automatic 194branch target alignment. 195 196@menu 197* Density Instructions:: Using Density Instructions. 198* Xtensa Automatic Alignment:: Automatic Instruction Alignment. 199@end menu 200 201@node Density Instructions 202@subsection Using Density Instructions 203@cindex density instructions 204 205The Xtensa instruction set has a code density option that provides 20616-bit versions of some of the most commonly used opcodes. Use of these 207opcodes can significantly reduce code size. When possible, the 208assembler automatically translates generic instructions from the core 209Xtensa instruction set into equivalent instructions from the Xtensa code 210density option. This translation can be disabled by using specific 211opcodes (@pxref{Xtensa Opcodes, ,Opcode Names}), by using the 212@samp{--no-density} command-line option (@pxref{Xtensa Options, ,Command 213Line Options}), or by using the @code{no-density} directive 214(@pxref{Density Directive, ,density}). 215 216It is a good idea @emph{not} to use the density instructions directly. 217The assembler will automatically select dense instructions where 218possible. If you later need to avoid using the code density option, you 219can disable it in the assembler without having to modify the code. 220 221@node Xtensa Automatic Alignment 222@subsection Automatic Instruction Alignment 223@cindex alignment of @code{LOOP} instructions 224@cindex alignment of @code{ENTRY} instructions 225@cindex alignment of branch targets 226@cindex @code{LOOP} instructions, alignment 227@cindex @code{ENTRY} instructions, alignment 228@cindex branch target alignment 229 230The Xtensa assembler will automatically align certain instructions, both 231to optimize performance and to satisfy architectural requirements. 232 233When the @code{--target-@-align} command-line option is enabled 234(@pxref{Xtensa Options, ,Command Line Options}), the assembler attempts 235to widen density instructions preceding a branch target so that the 236target instruction does not cross a 4-byte boundary. Similarly, the 237assembler also attempts to align each instruction following a call 238instruction. If there are not enough preceding safe density 239instructions to align a target, no widening will be performed. This 240alignment has the potential to reduce branch penalties at some expense 241in code size. The assembler will not attempt to align labels with the 242prefixes @code{.Ln} and @code{.LM}, since these labels are used for 243debugging information and are not typically branch targets. 244 245The @code{LOOP} family of instructions must be aligned on either a 1 or 2462 mod 4 byte boundary. The assembler knows about this restriction and 247inserts the minimal number of 2 or 3 byte no-op instructions 248to satisfy it. When no-op instructions are added, any label immediately 249preceding the original loop will be moved in order to refer to the loop 250instruction, not the newly generated no-op instruction. 251 252Similarly, the @code{ENTRY} instruction must be aligned on a 0 mod 4 253byte boundary. The assembler satisfies this requirement by inserting 254zero bytes when required. In addition, labels immediately preceding the 255@code{ENTRY} instruction will be moved to the newly aligned instruction 256location. 257 258@node Xtensa Relaxation 259@section Xtensa Relaxation 260@cindex relaxation 261 262When an instruction operand is outside the range allowed for that 263particular instruction field, @code{@value{AS}} can transform the code 264to use a functionally-equivalent instruction or sequence of 265instructions. This process is known as @dfn{relaxation}. This is 266typically done for branch instructions because the distance of the 267branch targets is not known until assembly-time. The Xtensa assembler 268offers branch relaxation and also extends this concept to function 269calls, @code{MOVI} instructions and other instructions with immediate 270fields. 271 272@menu 273* Xtensa Branch Relaxation:: Relaxation of Branches. 274* Xtensa Call Relaxation:: Relaxation of Function Calls. 275* Xtensa Immediate Relaxation:: Relaxation of other Immediate Fields. 276@end menu 277 278@node Xtensa Branch Relaxation 279@subsection Conditional Branch Relaxation 280@cindex relaxation of branch instructions 281@cindex branch instructions, relaxation 282 283When the target of a branch is too far away from the branch itself, 284i.e., when the offset from the branch to the target is too large to fit 285in the immediate field of the branch instruction, it may be necessary to 286replace the branch with a branch around a jump. For example, 287 288@smallexample 289 beqz a2, L 290@end smallexample 291 292may result in: 293 294@smallexample 295 bnez.n a2, M 296 j L 297M: 298@end smallexample 299 300(The @code{BNEZ.N} instruction would be used in this example only if the 301density option is available. Otherwise, @code{BNEZ} would be used.) 302 303@node Xtensa Call Relaxation 304@subsection Function Call Relaxation 305@cindex relaxation of call instructions 306@cindex call instructions, relaxation 307 308Function calls may require relaxation because the Xtensa immediate call 309instructions (@code{CALL0}, @code{CALL4}, @code{CALL8} and 310@code{CALL12}) provide a PC-relative offset of only 512 Kbytes in either 311direction. For larger programs, it may be necessary to use indirect 312calls (@code{CALLX0}, @code{CALLX4}, @code{CALLX8} and @code{CALLX12}) 313where the target address is specified in a register. The Xtensa 314assembler can automatically relax immediate call instructions into 315indirect call instructions. This relaxation is done by loading the 316address of the called function into the callee's return address register 317and then using a @code{CALLX} instruction. So, for example: 318 319@smallexample 320 call8 func 321@end smallexample 322 323might be relaxed to: 324 325@smallexample 326 .literal .L1, func 327 l32r a8, .L1 328 callx8 a8 329@end smallexample 330 331Because the addresses of targets of function calls are not generally 332known until link-time, the assembler must assume the worst and relax all 333the calls to functions in other source files, not just those that really 334will be out of range. The linker can recognize calls that were 335unnecessarily relaxed, but it can only partially remove the overhead 336introduced by the assembler. 337 338Call relaxation has a negative effect 339on both code size and performance, so this relaxation is disabled by 340default. If a program is too large and some of the calls are out of 341range, function call relaxation can be enabled using the 342@samp{--longcalls} command-line option or the @code{longcalls} directive 343(@pxref{Longcalls Directive, ,longcalls}). 344 345@node Xtensa Immediate Relaxation 346@subsection Other Immediate Field Relaxation 347@cindex immediate fields, relaxation 348@cindex relaxation of immediate fields 349 350@cindex @code{MOVI} instructions, relaxation 351@cindex relaxation of @code{MOVI} instructions 352The @code{MOVI} machine instruction can only materialize values in the 353range from -2048 to 2047. Values outside this range are best 354materialized with @code{L32R} instructions. Thus: 355 356@smallexample 357 movi a0, 100000 358@end smallexample 359 360is assembled into the following machine code: 361 362@smallexample 363 .literal .L1, 100000 364 l32r a0, .L1 365@end smallexample 366 367@cindex @code{L8UI} instructions, relaxation 368@cindex @code{L16SI} instructions, relaxation 369@cindex @code{L16UI} instructions, relaxation 370@cindex @code{L32I} instructions, relaxation 371@cindex relaxation of @code{L8UI} instructions 372@cindex relaxation of @code{L16SI} instructions 373@cindex relaxation of @code{L16UI} instructions 374@cindex relaxation of @code{L32I} instructions 375The @code{L8UI} machine instruction can only be used with immediate 376offsets in the range from 0 to 255. The @code{L16SI} and @code{L16UI} 377machine instructions can only be used with offsets from 0 to 510. The 378@code{L32I} machine instruction can only be used with offsets from 0 to 3791020. A load offset outside these ranges can be materalized with 380an @code{L32R} instruction if the destination register of the load 381is different than the source address register. For example: 382 383@smallexample 384 l32i a1, a0, 2040 385@end smallexample 386 387is translated to: 388 389@smallexample 390 .literal .L1, 2040 391 l32r a1, .L1 392 addi a1, a0, a1 393 l32i a1, a1, 0 394@end smallexample 395 396@noindent 397If the load destination and source address register are the same, an 398out-of-range offset causes an error. 399 400@cindex @code{ADDI} instructions, relaxation 401@cindex relaxation of @code{ADDI} instructions 402The Xtensa @code{ADDI} instruction only allows immediate operands in the 403range from -128 to 127. There are a number of alternate instruction 404sequences for the generic @code{ADDI} operation. First, if the 405immediate is 0, the @code{ADDI} will be turned into a @code{MOV.N} 406instruction (or the equivalent @code{OR} instruction if the code density 407option is not available). If the @code{ADDI} immediate is outside of 408the range -128 to 127, but inside the range -32896 to 32639, an 409@code{ADDMI} instruction or @code{ADDMI}/@code{ADDI} sequence will be 410used. Finally, if the immediate is outside of this range and a free 411register is available, an @code{L32R}/@code{ADD} sequence will be used 412with a literal allocated from the literal pool. 413 414For example: 415 416@smallexample 417 addi a5, a6, 0 418 addi a5, a6, 512 419 addi a5, a6, 513 420 addi a5, a6, 50000 421@end smallexample 422 423is assembled into the following: 424 425@smallexample 426 .literal .L1, 50000 427 mov.n a5, a6 428 addmi a5, a6, 0x200 429 addmi a5, a6, 0x200 430 addi a5, a5, 1 431 l32r a5, .L1 432 add a5, a6, a5 433@end smallexample 434 435@node Xtensa Directives 436@section Directives 437@cindex Xtensa directives 438@cindex directives, Xtensa 439 440The Xtensa assember supports a region-based directive syntax: 441 442@smallexample 443 .begin @var{directive} [@var{options}] 444 @dots{} 445 .end @var{directive} 446@end smallexample 447 448All the Xtensa-specific directives that apply to a region of code use 449this syntax. 450 451The directive applies to code between the @code{.begin} and the 452@code{.end}. The state of the option after the @code{.end} reverts to 453what it was before the @code{.begin}. 454A nested @code{.begin}/@code{.end} region can further 455change the state of the directive without having to be aware of its 456outer state. For example, consider: 457 458@smallexample 459 .begin no-density 460L: add a0, a1, a2 461 .begin density 462M: add a0, a1, a2 463 .end density 464N: add a0, a1, a2 465 .end no-density 466@end smallexample 467 468The generic @code{ADD} opcodes at @code{L} and @code{N} in the outer 469@code{no-density} region both result in @code{ADD} machine instructions, 470but the assembler selects an @code{ADD.N} instruction for the generic 471@code{ADD} at @code{M} in the inner @code{density} region. 472 473The advantage of this style is that it works well inside macros which can 474preserve the context of their callers. 475 476@cindex precedence of directives 477@cindex directives, precedence 478When command-line options and assembler directives are used at the same 479time and conflict, the one that overrides a default behavior takes 480precedence over one that is the same as the default. For example, if 481the code density option is available, the default is to select density 482instructions whenever possible. So, if the above is assembled with the 483@samp{--no-density} flag, which overrides the default, all the generic 484@code{ADD} instructions result in @code{ADD} machine instructions. If 485assembled with the @samp{--density} flag, which is already the default, 486the @code{no-density} directive takes precedence and only one of 487the generic @code{ADD} instructions is optimized to be a @code{ADD.N} 488machine instruction. An underscore prefix identifying a specific opcode 489always takes precedence over directives and command-line flags. 490 491The following directives are available: 492@menu 493* Density Directive:: Disable Use of Density Instructions. 494* Relax Directive:: Disable Assembler Relaxation. 495* Longcalls Directive:: Use Indirect Calls for Greater Range. 496* Generics Directive:: Disable All Assembler Transformations. 497* Literal Directive:: Intermix Literals with Instructions. 498* Literal Position Directive:: Specify Inline Literal Pool Locations. 499* Literal Prefix Directive:: Specify Literal Section Name Prefix. 500* Freeregs Directive:: List Registers Available for Assembler Use. 501* Frame Directive:: Describe a stack frame. 502@end menu 503 504@node Density Directive 505@subsection density 506@cindex @code{density} directive 507@cindex @code{no-density} directive 508 509The @code{density} and @code{no-density} directives enable or disable 510optimization of generic instructions into density instructions within 511the region. @xref{Density Instructions, ,Using Density Instructions}. 512 513@smallexample 514 .begin [no-]density 515 .end [no-]density 516@end smallexample 517 518This optimization is enabled by default unless the Xtensa configuration 519does not support the code density option or the @samp{--no-density} 520command-line option was specified. 521 522@node Relax Directive 523@subsection relax 524@cindex @code{relax} directive 525@cindex @code{no-relax} directive 526 527The @code{relax} directive enables or disables relaxation 528within the region. @xref{Xtensa Relaxation, ,Xtensa Relaxation}. 529Note: In the current implementation, these directives also control 530whether assembler optimizations are performed, making them equivalent to 531the @code{generics} and @code{no-generics} directives. 532 533@smallexample 534 .begin [no-]relax 535 .end [no-]relax 536@end smallexample 537 538Relaxation is enabled by default unless the @samp{--no-relax} 539command-line option was specified. 540 541@node Longcalls Directive 542@subsection longcalls 543@cindex @code{longcalls} directive 544@cindex @code{no-longcalls} directive 545 546The @code{longcalls} directive enables or disables function call 547relaxation. @xref{Xtensa Call Relaxation, ,Function Call Relaxation}. 548 549@smallexample 550 .begin [no-]longcalls 551 .end [no-]longcalls 552@end smallexample 553 554Call relaxation is disabled by default unless the @samp{--longcalls} 555command-line option is specified. 556 557@node Generics Directive 558@subsection generics 559@cindex @code{generics} directive 560@cindex @code{no-generics} directive 561 562This directive enables or disables all assembler transformation, 563including relaxation (@pxref{Xtensa Relaxation, ,Xtensa Relaxation}) and 564optimization (@pxref{Xtensa Optimizations, ,Xtensa Optimizations}). 565 566@smallexample 567 .begin [no-]generics 568 .end [no-]generics 569@end smallexample 570 571Disabling generics is roughly equivalent to adding an underscore prefix 572to every opcode within the region, so that every opcode is treated as a 573specific opcode. @xref{Xtensa Opcodes, ,Opcode Names}. In the current 574implementation of @code{@value{AS}}, built-in macros are also disabled 575within a @code{no-generics} region. 576 577@node Literal Directive 578@subsection literal 579@cindex @code{literal} directive 580 581The @code{.literal} directive is used to define literal pool data, i.e., 582read-only 32-bit data accessed via @code{L32R} instructions. 583 584@smallexample 585 .literal @var{label}, @var{value}[, @var{value}@dots{}] 586@end smallexample 587 588This directive is similar to the standard @code{.word} directive, except 589that the actual location of the literal data is determined by the 590assembler and linker, not by the position of the @code{.literal} 591directive. Using this directive gives the assembler freedom to locate 592the literal data in the most appropriate place and possibly to combine 593identical literals. For example, the code: 594 595@smallexample 596 entry sp, 40 597 .literal .L1, sym 598 l32r a4, .L1 599@end smallexample 600 601can be used to load a pointer to the symbol @code{sym} into register 602@code{a4}. The value of @code{sym} will not be placed between the 603@code{ENTRY} and @code{L32R} instructions; instead, the assembler puts 604the data in a literal pool. 605 606By default literal pools are placed in a separate section; however, when 607using the @samp{--text-@-section-@-literals} option (@pxref{Xtensa 608Options, ,Command Line Options}), the literal pools are placed in the 609current section. These text section literal pools are created 610automatically before @code{ENTRY} instructions and manually after 611@samp{.literal_position} directives (@pxref{Literal Position Directive, 612,literal_position}). If there are no preceding @code{ENTRY} 613instructions or @code{.literal_position} directives, the assembler will 614print a warning and place the literal pool at the beginning of the 615current section. In such cases, explicit @code{.literal_position} 616directives should be used to place the literal pools. 617 618@node Literal Position Directive 619@subsection literal_position 620@cindex @code{literal_position} directive 621 622When using @samp{--text-@-section-@-literals} to place literals inline 623in the section being assembled, the @code{.literal_position} directive 624can be used to mark a potential location for a literal pool. 625 626@smallexample 627 .literal_position 628@end smallexample 629 630The @code{.literal_position} directive is ignored when the 631@samp{--text-@-section-@-literals} option is not used. 632 633The assembler will automatically place text section literal pools 634before @code{ENTRY} instructions, so the @code{.literal_position} 635directive is only needed to specify some other location for a literal 636pool. You may need to add an explicit jump instruction to skip over an 637inline literal pool. 638 639For example, an interrupt vector does not begin with an @code{ENTRY} 640instruction so the assembler will be unable to automatically find a good 641place to put a literal pool. Moreover, the code for the interrupt 642vector must be at a specific starting address, so the literal pool 643cannot come before the start of the code. The literal pool for the 644vector must be explicitly positioned in the middle of the vector (before 645any uses of the literals, of course). The @code{.literal_position} 646directive can be used to do this. In the following code, the literal 647for @samp{M} will automatically be aligned correctly and is placed after 648the unconditional jump. 649 650@smallexample 651 .global M 652code_start: 653 j continue 654 .literal_position 655 .align 4 656continue: 657 movi a4, M 658@end smallexample 659 660@node Literal Prefix Directive 661@subsection literal_prefix 662@cindex @code{literal_prefix} directive 663 664The @code{literal_prefix} directive allows you to specify different 665sections to hold literals from different portions of an assembly file. 666With this directive, a single assembly file can be used to generate code 667into multiple sections, including literals generated by the assembler. 668 669@smallexample 670 .begin literal_prefix [@var{name}] 671 .end literal_prefix 672@end smallexample 673 674For the code inside the delimited region, the assembler puts literals in 675the section @code{@var{name}.literal}. If this section does not yet 676exist, the assembler creates it. The @var{name} parameter is 677optional. If @var{name} is not specified, the literal prefix is set to 678the ``default'' for the file. This default is usually @code{.literal} 679but can be changed with the @samp{--rename-section} command-line 680argument. 681 682@node Freeregs Directive 683@subsection freeregs 684@cindex @code{freeregs} directive 685 686This directive tells the assembler that the given registers are unused 687in the region. 688 689@smallexample 690 .begin freeregs @var{ri}[,@var{ri}@dots{}] 691 .end freeregs 692@end smallexample 693 694This allows the assembler to use these registers for relaxations or 695optimizations. (They are actually only for relaxations at present, but 696the possibility of optimizations exists in the future.) 697 698Nested @code{freeregs} directives can be used to add additional registers 699to the list of those available to the assembler. For example: 700 701@smallexample 702 .begin freeregs a3, a4 703 .begin freeregs a5 704@end smallexample 705 706has the effect of declaring @code{a3}, @code{a4}, and @code{a5} all free. 707 708@node Frame Directive 709@subsection frame 710@cindex @code{frame} directive 711 712This directive tells the assembler to emit information to allow the 713debugger to locate a function's stack frame. The syntax is: 714 715@smallexample 716 .frame @var{reg}, @var{size} 717@end smallexample 718 719where @var{reg} is the register used to hold the frame pointer (usually 720the same as the stack pointer) and @var{size} is the size in bytes of 721the stack frame. The @code{.frame} directive is typically placed 722immediately after the @code{ENTRY} instruction for a function. 723 724In almost all circumstances, this information just duplicates the 725information given in the function's @code{ENTRY} instruction; however, 726there are two cases where this is not true: 727 728@enumerate 729@item 730The size of the stack frame is too big to fit in the immediate field 731of the @code{ENTRY} instruction. 732 733@item 734The frame pointer is different than the stack pointer, as with functions 735that call @code{alloca}. 736@end enumerate 737 738@c Local Variables: 739@c fill-column: 72 740@c End: 741