gas/doc/c-mips.texi

   1 @c Copyright (C) 1991, 92, 93, 94, 95, 1997 Free Software Foundation, Inc.
   2 @c This is part of the GAS manual.
   3 @c For copying conditions, see the file as.texinfo.
   4 @ifset GENERIC
   5 @page
   6 @node MIPS-Dependent
   7 @chapter MIPS Dependent Features
   8 @end ifset
   9 @ifclear GENERIC
  10 @node Machine Dependencies
  11 @chapter MIPS Dependent Features
  12 @end ifclear
  13
  14 @cindex MIPS processor
  15 @sc{gnu} @code{@value{AS}} for @sc{mips} architectures supports several
  16 different @sc{mips} processors, and MIPS ISA levels I through V, MIPS32,
  17 and MIPS64.  For information about the @sc{mips} instruction set, see
  18 @cite{MIPS RISC Architecture}, by Kane and Heindrich (Prentice-Hall).
  19 For an overview of @sc{mips} assembly conventions, see ``Appendix D:
  20 Assembly Language Programming'' in the same work.
  21
  22 @menu
  23 * MIPS Opts::           Assembler options
  24 * MIPS Object::         ECOFF object code
  25 * MIPS Stabs::          Directives for debugging information
  26 * MIPS ISA::            Directives to override the ISA level
  27 * MIPS autoextend::     Directives for extending MIPS 16 bit instructions
  28 * MIPS insn::           Directive to mark data as an instruction
  29 * MIPS option stack::   Directives to save and restore options
  30 @end menu
  31
  32 @node MIPS Opts
  33 @section Assembler options
  34
  35 The @sc{mips} configurations of @sc{gnu} @code{@value{AS}} support these
  36 special options:
  37
  38 @table @code
  39 @cindex @code{-G} option (MIPS)
  40 @item -G @var{num}
  41 This option sets the largest size of an object that can be referenced
  42 implicitly with the @code{gp} register.  It is only accepted for targets
  43 that use @sc{ecoff} format.  The default value is 8.
  44
  45 @cindex @code{-EB} option (MIPS)
  46 @cindex @code{-EL} option (MIPS)
  47 @cindex MIPS big-endian output
  48 @cindex MIPS little-endian output
  49 @cindex big-endian output, MIPS
  50 @cindex little-endian output, MIPS
  51 @item -EB
  52 @itemx -EL
  53 Any @sc{mips} configuration of @code{@value{AS}} can select big-endian or
  54 little-endian output at run time (unlike the other @sc{gnu} development
  55 tools, which must be configured for one or the other).  Use @samp{-EB}
  56 to select big-endian output, and @samp{-EL} for little-endian.
  57
  58 @cindex MIPS architecture options
  59 @item -mips1
  60 @itemx -mips2
  61 @itemx -mips3
  62 @itemx -mips4
  63 @itemx -mips5
  64 @itemx -mips32
  65 @itemx -mips64
  66 Generate code for a particular MIPS Instruction Set Architecture level.
  67 @samp{-mips1} corresponds to the @sc{r2000} and @sc{r3000} processors,
  68 @samp{-mips2} to the @sc{r6000} processor, @samp{-mips3} to the
  69 @sc{r4000} processor, and @samp{-mips4} to the @sc{r8000} and
  70 @sc{r10000} processors.  @samp{-mips5}, @samp{-mips32}, and
  71 @samp{-mips64} correspond to generic @sc{MIPS V}, @sc{MIPS32}, and
  72 @sc{MIPS64} ISA processors, respectively.  You can also switch
  73 instruction sets during the assembly; see @ref{MIPS ISA, Directives to
  74 override the ISA level}.
  75
  76 @item -mgp32
  77 Assume that 32-bit general purpose registers are available.  This
  78 affects synthetic instructions such as @code{move}, which will assemble
  79 to a 32-bit or a 64-bit instruction depending on this flag.  On some
  80 MIPS variants there is a 32-bit mode flag; when this flag is set,
  81 64-bit instructions generate a trap.  Also, some 32-bit OSes only save
  82 the 32-bit registers on a context switch, so it is essential never to
  83 use the 64-bit registers.
  84
  85 @item -mgp64
  86 Assume that 64-bit general purpose registers are available.  This is
  87 provided in the interests of symmetry with -gp32.
  88
  89 @item -mips16
  90 @itemx -no-mips16
  91 Generate code for the MIPS 16 processor.  This is equivalent to putting
  92 @samp{.set mips16} at the start of the assembly file.  @samp{-no-mips16}
  93 turns off this option.
  94
  95 @item -mfix7000
  96 @itemx -no-mfix7000
  97 Cause nops to be inserted if the read of the destination register
  98 of an mfhi or mflo instruction occurs in the following two instructions.
  99
 100 @item -m4010
 101 @itemx -no-m4010
 102 Generate code for the LSI @sc{r4010} chip.  This tells the assembler to
 103 accept the @sc{r4010} specific instructions (@samp{addciu}, @samp{ffc},
 104 etc.), and to not schedule @samp{nop} instructions around accesses to
 105 the @samp{HI} and @samp{LO} registers.  @samp{-no-m4010} turns off this
 106 option.
 107
 108 @item -m4650
 109 @itemx -no-m4650
 110 Generate code for the MIPS @sc{r4650} chip.  This tells the assembler to accept
 111 the @samp{mad} and @samp{madu} instruction, and to not schedule @samp{nop}
 112 instructions around accesses to the @samp{HI} and @samp{LO} registers.
 113 @samp{-no-m4650} turns off this option.
 114
 115 @itemx -m3900
 116 @itemx -no-m3900
 117 @itemx -m4100
 118 @itemx -no-m4100
 119 For each option @samp{-m@var{nnnn}}, generate code for the MIPS
 120 @sc{r@var{nnnn}} chip.  This tells the assembler to accept instructions
 121 specific to that chip, and to schedule for that chip's hazards.
 122
 123 @item -mcpu=@var{cpu}
 124 Generate code for a particular MIPS cpu.  It is exactly equivalent to
 125 @samp{-m@var{cpu}}, except that there are more value of @var{cpu}
 126 understood.  Valid @var{cpu} value are:
 127
 128 @quotation
 129 2000,
 130 3000,
 131 3900,
 132 4000,
 133 4010,
 134 4100,
 135 4111,
 136 4300,
 137 4400,
 138 4600,
 139 4650,
 140 5000,
 141 rm5200,
 142 rm5230,
 143 rm5231,
 144 rm5261,
 145 rm5721,
 146 6000,
 147 rm7000,
 148 8000,
 149 10000,
 150 mips32-4k,
 151 sb1
 152 @end quotation
 153
 154
 155 @cindex @code{-nocpp} ignored (MIPS)
 156 @item -nocpp
 157 This option is ignored.  It is accepted for command-line compatibility with
 158 other assemblers, which use it to turn off C style preprocessing.  With
 159 @sc{gnu} @code{@value{AS}}, there is no need for @samp{-nocpp}, because the
 160 @sc{gnu} assembler itself never runs the C preprocessor.
 161
 162 @item --construct-floats
 163 @itemx --no-construct-floats
 164 @cindex --construct-floats
 165 @cindex --no-construct-floats
 166 The @code{--no-construct-floats} option disables the construction of
 167 double width floating point constants by loading the two halves of the
 168 value into the two single width floating point registers that make up
 169 the double width register.  This feature is useful if the processor
 170 support the FR bit in its status  register, and this bit is known (by
 171 the programmer) to be set.  This bit prevents the aliasing of the double
 172 width register by the single width registers.
 173
 174 By default @code{--construct-floats} is selected, allowing construction
 175 of these floating point constants.
 176
 177 @item --trap
 178 @itemx --no-break
 179 @c FIXME!  (1) reflect these options (next item too) in option summaries;
 180 @c         (2) stop teasing, say _which_ instructions expanded _how_.
 181 @code{@value{AS}} automatically macro expands certain division and
 182 multiplication instructions to check for overflow and division by zero.  This
 183 option causes @code{@value{AS}} to generate code to take a trap exception
 184 rather than a break exception when an error is detected.  The trap instructions
 185 are only supported at Instruction Set Architecture level 2 and higher.
 186
 187 @item --break
 188 @itemx --no-trap
 189 Generate code to take a break exception rather than a trap exception when an
 190 error is detected.  This is the default.
 191 @end table
 192
 193 @node MIPS Object
 194 @section MIPS ECOFF object code
 195
 196 @cindex ECOFF sections
 197 @cindex MIPS ECOFF sections
 198 Assembling for a @sc{mips} @sc{ecoff} target supports some additional sections
 199 besides the usual @code{.text}, @code{.data} and @code{.bss}.  The
 200 additional sections are @code{.rdata}, used for read-only data,
 201 @code{.sdata}, used for small data, and @code{.sbss}, used for small
 202 common objects.
 203
 204 @cindex small objects, MIPS ECOFF
 205 @cindex @code{gp} register, MIPS
 206 When assembling for @sc{ecoff}, the assembler uses the @code{$gp} (@code{$28})
 207 register to form the address of a ``small object''.  Any object in the
 208 @code{.sdata} or @code{.sbss} sections is considered ``small'' in this sense.
 209 For external objects, or for objects in the @code{.bss} section, you can use
 210 the @code{@value{GCC}} @samp{-G} option to control the size of objects addressed via
 211 @code{$gp}; the default value is 8, meaning that a reference to any object
 212 eight bytes or smaller uses @code{$gp}.  Passing @samp{-G 0} to
 213 @code{@value{AS}} prevents it from using the @code{$gp} register on the basis
 214 of object size (but the assembler uses @code{$gp} for objects in @code{.sdata}
 215 or @code{sbss} in any case).  The size of an object in the @code{.bss} section
 216 is set by the @code{.comm} or @code{.lcomm} directive that defines it.  The
 217 size of an external object may be set with the @code{.extern} directive.  For
 218 example, @samp{.extern sym,4} declares that the object at @code{sym} is 4 bytes
 219 in length, whie leaving @code{sym} otherwise undefined.
 220
 221 Using small @sc{ecoff} objects requires linker support, and assumes that the
 222 @code{$gp} register is correctly initialized (normally done automatically by
 223 the startup code).  @sc{mips} @sc{ecoff} assembly code must not modify the
 224 @code{$gp} register.
 225
 226 @node MIPS Stabs
 227 @section Directives for debugging information
 228
 229 @cindex MIPS debugging directives
 230 @sc{mips} @sc{ecoff} @code{@value{AS}} supports several directives used for
 231 generating debugging information which are not support by traditional @sc{mips}
 232 assemblers.  These are @code{.def}, @code{.endef}, @code{.dim}, @code{.file},
 233 @code{.scl}, @code{.size}, @code{.tag}, @code{.type}, @code{.val},
 234 @code{.stabd}, @code{.stabn}, and @code{.stabs}.  The debugging information
 235 generated by the three @code{.stab} directives can only be read by @sc{gdb},
 236 not by traditional @sc{mips} debuggers (this enhancement is required to fully
 237 support C++ debugging).  These directives are primarily used by compilers, not
 238 assembly language programmers!
 239
 240 @node MIPS ISA
 241 @section Directives to override the ISA level
 242
 243 @cindex MIPS ISA override
 244 @kindex @code{.set mips@var{n}}
 245 @sc{gnu} @code{@value{AS}} supports an additional directive to change
 246 the @sc{mips} Instruction Set Architecture level on the fly: @code{.set
 247 mips@var{n}}.  @var{n} should be a number from 0 to 5, or 32 or 64.
 248 The values 1 to 5, 32, and 64 make the assembler accept instructions
 249 for the corresponding @sc{isa} level, from that point on in the
 250 assembly.  @code{.set mips@var{n}} affects not only which instructions
 251 are permitted, but also how certain macros are expanded.  @code{.set
 252 mips0} restores the @sc{isa} level to its original level: either the
 253 level you selected with command line options, or the default for your
 254 configuration.  You can use this feature to permit specific @sc{r4000}
 255 instructions while assembling in 32 bit mode.  Use this directive with
 256 care!
 257
 258 The directive @samp{.set mips16} puts the assembler into MIPS 16 mode,
 259 in which it will assemble instructions for the MIPS 16 processor.  Use
 260 @samp{.set nomips16} to return to normal 32 bit mode.
 261
 262 Traditional @sc{mips} assemblers do not support this directive.
 263
 264 @node MIPS autoextend
 265 @section Directives for extending MIPS 16 bit instructions
 266
 267 @kindex @code{.set autoextend}
 268 @kindex @code{.set noautoextend}
 269 By default, MIPS 16 instructions are automatically extended to 32 bits
 270 when necessary.  The directive @samp{.set noautoextend} will turn this
 271 off.  When @samp{.set noautoextend} is in effect, any 32 bit instruction
 272 must be explicitly extended with the @samp{.e} modifier (e.g.,
 273 @samp{li.e $4,1000}).  The directive @samp{.set autoextend} may be used
 274 to once again automatically extend instructions when necessary.
 275
 276 This directive is only meaningful when in MIPS 16 mode.  Traditional
 277 @sc{mips} assemblers do not support this directive.
 278
 279 @node MIPS insn
 280 @section Directive to mark data as an instruction
 281
 282 @kindex @code{.insn}
 283 The @code{.insn} directive tells @code{@value{AS}} that the following
 284 data is actually instructions.  This makes a difference in MIPS 16 mode:
 285 when loading the address of a label which precedes instructions,
 286 @code{@value{AS}} automatically adds 1 to the value, so that jumping to
 287 the loaded address will do the right thing.
 288
 289 @node MIPS option stack
 290 @section Directives to save and restore options
 291
 292 @cindex MIPS option stack
 293 @kindex @code{.set push}
 294 @kindex @code{.set pop}
 295 The directives @code{.set push} and @code{.set pop} may be used to save
 296 and restore the current settings for all the options which are
 297 controlled by @code{.set}.  The @code{.set push} directive saves the
 298 current settings on a stack.  The @code{.set pop} directive pops the
 299 stack and restores the settings.
 300
 301 These directives can be useful inside an macro which must change an
 302 option such as the ISA level or instruction reordering but does not want
 303 to change the state of the code which invoked the macro.
 304
 305 Traditional @sc{mips} assemblers do not support these directives.