contrib/binutils-2.25/gas/doc/c-m32r.texi

   1 @c Copyright (C) 1991-2014 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 M32R-Dependent
   7 @chapter M32R Dependent Features
   8 @end ifset
   9 @ifclear GENERIC
  10 @node Machine Dependencies
  11 @chapter M32R Dependent Features
  12 @end ifclear
  13
  14 @cindex M32R support
  15 @menu
  16 * M32R-Opts::                   M32R Options
  17 * M32R-Directives::             M32R Directives
  18 * M32R-Warnings::               M32R Warnings
  19 @end menu
  20
  21 @node M32R-Opts
  22 @section M32R Options
  23
  24 @cindex options, M32R
  25 @cindex M32R options
  26
  27 The Renease M32R version of @code{@value{AS}} has a few machine
  28 dependent options:
  29
  30 @table @code
  31
  32 @item -m32rx
  33 @cindex @samp{-m32rx} option, M32RX
  34 @cindex architecture options, M32RX
  35 @cindex M32R architecture options
  36 @code{@value{AS}} can assemble code for several different members of the
  37 Renesas M32R family.  Normally the default is to assemble code for
  38 the M32R microprocessor.  This option may be used to change the default
  39 to the M32RX microprocessor, which adds some more instructions to the
  40 basic M32R instruction set, and some additional parameters to some of
  41 the original instructions.
  42
  43 @item -m32r2
  44 @cindex @samp{-m32rx} option, M32R2
  45 @cindex architecture options, M32R2
  46 @cindex M32R architecture options
  47 This option changes the target processor to the M32R2
  48 microprocessor.
  49
  50 @item -m32r
  51 @cindex @samp{-m32r} option, M32R
  52 @cindex architecture options, M32R
  53 @cindex M32R architecture options
  54 This option can be used to restore the assembler's default behaviour of
  55 assembling for the M32R microprocessor.  This can be useful if the
  56 default has been changed by a previous command line option.
  57
  58 @item -little
  59 @cindex @code{-little} option, M32R
  60 This option tells the assembler to produce little-endian code and
  61 data.  The default is dependent upon how the toolchain was
  62 configured.
  63
  64 @item -EL
  65 @cindex @code{-EL} option, M32R
  66 This is a synonym for @emph{-little}.
  67
  68 @item -big
  69 @cindex @code{-big} option, M32R
  70 This option tells the assembler to produce big-endian code and
  71 data.
  72
  73 @item -EB
  74 @cindex @code{-EB} option, M32R
  75 This is a synonum for @emph{-big}.
  76
  77 @item -KPIC
  78 @cindex @code{-KPIC} option, M32R
  79 @cindex PIC code generation for M32R
  80 This option specifies that the output of the assembler should be
  81 marked as position-independent code (PIC).
  82
  83 @item -parallel
  84 @cindex @code{-parallel} option, M32RX
  85 This option tells the assembler to attempts to combine two sequential
  86 instructions into a single, parallel instruction, where it is legal to
  87 do so.
  88
  89 @item -no-parallel
  90 @cindex @code{-no-parallel} option, M32RX
  91 This option disables a previously enabled @emph{-parallel} option.
  92
  93 @item -no-bitinst
  94 @cindex @samp{-no-bitinst}, M32R2
  95 This option disables the support for the extended bit-field
  96 instructions provided by the M32R2.  If this support needs to be
  97 re-enabled the @emph{-bitinst} switch can be used to restore it.
  98
  99 @item -O
 100 @cindex @code{-O} option, M32RX
 101 This option tells the assembler to attempt to optimize the
 102 instructions that it produces.  This includes filling delay slots and
 103 converting sequential instructions into parallel ones.  This option
 104 implies @emph{-parallel}.
 105
 106 @item -warn-explicit-parallel-conflicts
 107 @cindex @samp{-warn-explicit-parallel-conflicts} option, M32RX
 108 Instructs @code{@value{AS}} to produce warning messages when
 109 questionable parallel instructions are encountered.  This option is
 110 enabled by default, but @code{@value{GCC}} disables it when it invokes
 111 @code{@value{AS}} directly.  Questionable instructions are those whose
 112 behaviour would be different if they were executed sequentially.  For
 113 example the code fragment @samp{mv r1, r2 || mv r3, r1} produces a
 114 different result from @samp{mv r1, r2 \n mv r3, r1} since the former
 115 moves r1 into r3 and then r2 into r1, whereas the later moves r2 into r1
 116 and r3.
 117
 118 @item -Wp
 119 @cindex @samp{-Wp} option, M32RX
 120 This is a shorter synonym for the @emph{-warn-explicit-parallel-conflicts}
 121 option.
 122
 123 @item -no-warn-explicit-parallel-conflicts
 124 @cindex @samp{-no-warn-explicit-parallel-conflicts} option, M32RX
 125 Instructs @code{@value{AS}} not to produce warning messages when
 126 questionable parallel instructions are encountered.
 127
 128 @item -Wnp
 129 @cindex @samp{-Wnp} option, M32RX
 130 This is a shorter synonym for the @emph{-no-warn-explicit-parallel-conflicts}
 131 option.
 132
 133 @item -ignore-parallel-conflicts
 134 @cindex @samp{-ignore-parallel-conflicts} option, M32RX
 135 This option tells the assembler's to stop checking parallel
 136 instructions for constraint violations.  This ability is provided for
 137 hardware vendors testing chip designs and should not be used under
 138 normal circumstances.
 139
 140 @item -no-ignore-parallel-conflicts
 141 @cindex @samp{-no-ignore-parallel-conflicts} option, M32RX
 142 This option restores the assembler's default behaviour of checking
 143 parallel instructions to detect constraint violations.
 144
 145 @item -Ip
 146 @cindex @samp{-Ip} option, M32RX
 147 This is a shorter synonym for the @emph{-ignore-parallel-conflicts}
 148 option.
 149
 150 @item -nIp
 151 @cindex @samp{-nIp} option, M32RX
 152 This is a shorter synonym for the @emph{-no-ignore-parallel-conflicts}
 153 option.
 154
 155 @item -warn-unmatched-high
 156 @cindex @samp{-warn-unmatched-high} option, M32R
 157 This option tells the assembler to produce a warning message if a
 158 @code{.high} pseudo op is encountered without a matching @code{.low}
 159 pseudo op.  The presence of such an unmatched pseudo op usually
 160 indicates a programming error.
 161
 162 @item -no-warn-unmatched-high
 163 @cindex @samp{-no-warn-unmatched-high} option, M32R
 164 Disables a previously enabled @emph{-warn-unmatched-high} option.
 165
 166 @item -Wuh
 167 @cindex @samp{-Wuh} option, M32RX
 168 This is a shorter synonym for the @emph{-warn-unmatched-high} option.
 169
 170 @item -Wnuh
 171 @cindex @samp{-Wnuh} option, M32RX
 172 This is a shorter synonym for the @emph{-no-warn-unmatched-high} option.
 173
 174 @end table
 175
 176 @node M32R-Directives
 177 @section M32R Directives
 178 @cindex directives, M32R
 179 @cindex M32R directives
 180
 181 The Renease M32R version of @code{@value{AS}} has a few architecture
 182 specific directives:
 183
 184 @table @code
 185
 186 @cindex @code{low} directive, M32R
 187 @item low @var{expression}
 188 The @code{low} directive computes the value of its expression and
 189 places the lower 16-bits of the result into the immediate-field of the
 190 instruction.  For example:
 191
 192 @smallexample
 193    or3   r0, r0, #low(0x12345678) ; compute r0 = r0 | 0x5678
 194    add3, r0, r0, #low(fred)   ; compute r0 = r0 + low 16-bits of address of fred
 195 @end smallexample
 196
 197 @item high @var{expression}
 198 @cindex @code{high} directive, M32R
 199 The @code{high} directive computes the value of its expression and
 200 places the upper 16-bits of the result into the immediate-field of the
 201 instruction.  For example:
 202
 203 @smallexample
 204    seth  r0, #high(0x12345678) ; compute r0 = 0x12340000
 205    seth, r0, #high(fred)       ; compute r0 = upper 16-bits of address of fred
 206 @end smallexample
 207
 208 @item shigh @var{expression}
 209 @cindex @code{shigh} directive, M32R
 210 The @code{shigh} directive is very similar to the @code{high}
 211 directive.  It also computes the value of its expression and places
 212 the upper 16-bits of the result into the immediate-field of the
 213 instruction.  The difference is that @code{shigh} also checks to see
 214 if the lower 16-bits could be interpreted as a signed number, and if
 215 so it assumes that a borrow will occur from the upper-16 bits.  To
 216 compensate for this the @code{shigh} directive pre-biases the upper
 217 16 bit value by adding one to it.  For example:
 218
 219 For example:
 220
 221 @smallexample
 222    seth  r0, #shigh(0x12345678) ; compute r0 = 0x12340000
 223    seth  r0, #shigh(0x00008000) ; compute r0 = 0x00010000
 224 @end smallexample
 225
 226 In the second example the lower 16-bits are 0x8000.  If these are
 227 treated as a signed value and sign extended to 32-bits then the value
 228 becomes 0xffff8000.  If this value is then added to 0x00010000 then
 229 the result is 0x00008000.
 230
 231 This behaviour is to allow for the different semantics of the
 232 @code{or3} and @code{add3} instructions.  The @code{or3} instruction
 233 treats its 16-bit immediate argument as unsigned whereas the
 234 @code{add3} treats its 16-bit immediate as a signed value.  So for
 235 example:
 236
 237 @smallexample
 238    seth  r0, #shigh(0x00008000)
 239    add3  r0, r0, #low(0x00008000)
 240 @end smallexample
 241
 242 Produces the correct result in r0, whereas:
 243
 244 @smallexample
 245    seth  r0, #shigh(0x00008000)
 246    or3   r0, r0, #low(0x00008000)
 247 @end smallexample
 248
 249 Stores 0xffff8000 into r0.
 250
 251 Note - the @code{shigh} directive does not know where in the assembly
 252 source code the lower 16-bits of the value are going set, so it cannot
 253 check to make sure that an @code{or3} instruction is being used rather
 254 than an @code{add3} instruction.  It is up to the programmer to make
 255 sure that correct directives are used.
 256
 257 @cindex @code{.m32r} directive, M32R
 258 @item .m32r
 259 The directive performs a similar thing as the @emph{-m32r} command
 260 line option.  It tells the assembler to only accept M32R instructions
 261 from now on.  An instructions from later M32R architectures are
 262 refused.
 263
 264 @cindex @code{.m32rx} directive, M32RX
 265 @item .m32rx
 266 The directive performs a similar thing as the @emph{-m32rx} command
 267 line option.  It tells the assembler to start accepting the extra
 268 instructions in the M32RX ISA as well as the ordinary M32R ISA.
 269
 270 @cindex @code{.m32r2} directive, M32R2
 271 @item .m32r2
 272 The directive performs a similar thing as the @emph{-m32r2} command
 273 line option.  It tells the assembler to start accepting the extra
 274 instructions in the M32R2 ISA as well as the ordinary M32R ISA.
 275
 276 @cindex @code{.little} directive, M32RX
 277 @item .little
 278 The directive performs a similar thing as the @emph{-little} command
 279 line option.  It tells the assembler to start producing little-endian
 280 code and data.  This option should be used with care as producing
 281 mixed-endian binary files is fraught with danger.
 282
 283 @cindex @code{.big} directive, M32RX
 284 @item .big
 285 The directive performs a similar thing as the @emph{-big} command
 286 line option.  It tells the assembler to start producing big-endian
 287 code and data.  This option should be used with care as producing
 288 mixed-endian binary files is fraught with danger.
 289
 290 @end table
 291
 292 @node M32R-Warnings
 293 @section M32R Warnings
 294
 295 @cindex warnings, M32R
 296 @cindex M32R warnings
 297
 298 There are several warning and error messages that can be produced by
 299 @code{@value{AS}} which are specific to the M32R:
 300
 301 @table @code
 302
 303 @item output of 1st instruction is the same as an input to 2nd instruction - is this intentional ?
 304 This message is only produced if warnings for explicit parallel
 305 conflicts have been enabled.  It indicates that the assembler has
 306 encountered a parallel instruction in which the destination register of
 307 the left hand instruction is used as an input register in the right hand
 308 instruction.  For example in this code fragment
 309 @samp{mv r1, r2 || neg r3, r1} register r1 is the destination of the
 310 move instruction and the input to the neg instruction.
 311
 312 @item output of 2nd instruction is the same as an input to 1st instruction - is this intentional ?
 313 This message is only produced if warnings for explicit parallel
 314 conflicts have been enabled.  It indicates that the assembler has
 315 encountered a parallel instruction in which the destination register of
 316 the right hand instruction is used as an input register in the left hand
 317 instruction.  For example in this code fragment
 318 @samp{mv r1, r2 || neg r2, r3} register r2 is the destination of the
 319 neg instruction and the input to the move instruction.
 320
 321 @item instruction @samp{...} is for the M32RX only
 322 This message is produced when the assembler encounters an instruction
 323 which is only supported by the M32Rx processor, and the @samp{-m32rx}
 324 command line flag has not been specified to allow assembly of such
 325 instructions.
 326
 327 @item unknown instruction @samp{...}
 328 This message is produced when the assembler encounters an instruction
 329 which it does not recognize.
 330
 331 @item only the NOP instruction can be issued in parallel on the m32r
 332 This message is produced when the assembler encounters a parallel
 333 instruction which does not involve a NOP instruction and the
 334 @samp{-m32rx} command line flag has not been specified.  Only the M32Rx
 335 processor is able to execute two instructions in parallel.
 336
 337 @item instruction @samp{...} cannot be executed in parallel.
 338 This message is produced when the assembler encounters a parallel
 339 instruction which is made up of one or two instructions which cannot be
 340 executed in parallel.
 341
 342 @item Instructions share the same execution pipeline
 343 This message is produced when the assembler encounters a parallel
 344 instruction whoes components both use the same execution pipeline.
 345
 346 @item Instructions write to the same destination register.
 347 This message is produced when the assembler encounters a parallel
 348 instruction where both components attempt to modify the same register.
 349 For example these code fragments will produce this message:
 350 @samp{mv r1, r2 || neg r1, r3}
 351 @samp{jl r0 || mv r14, r1}
 352 @samp{st r2, @@-r1 || mv r1, r3}
 353 @samp{mv r1, r2 || ld r0, @@r1+}
 354 @samp{cmp r1, r2 || addx r3, r4} (Both write to the condition bit)
 355
 356 @end table