contrib/binutils-2.27/gas/doc/c-msp430.texi

   1 @c Copyright (C) 2002-2016 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 MSP430-Dependent
   7 @chapter MSP 430 Dependent Features
   8 @end ifset
   9 @ifclear GENERIC
  10 @node Machine Dependencies
  11 @chapter MSP 430 Dependent Features
  12 @end ifclear
  13
  14 @cindex MSP 430 support
  15 @cindex 430 support
  16 @menu
  17 * MSP430 Options::              Options
  18 * MSP430 Syntax::               Syntax
  19 * MSP430 Floating Point::       Floating Point
  20 * MSP430 Directives::           MSP 430 Machine Directives
  21 * MSP430 Opcodes::              Opcodes
  22 * MSP430 Profiling Capability:: Profiling Capability
  23 @end menu
  24
  25 @node MSP430 Options
  26 @section Options
  27 @cindex MSP 430 options (none)
  28 @cindex options for MSP430 (none)
  29 @table @code
  30
  31 @item -mmcu
  32 selects the mcu architecture.  If the architecture is 430Xv2 then this
  33 also enables NOP generation unless the @option{-mN} is also specified.
  34
  35 @item -mcpu
  36 selects the cpu architecture.  If the architecture is 430Xv2 then this
  37 also enables NOP generation unless the @option{-mN} is also specified.
  38
  39 @item -msilicon-errata=@var{name}[,@var{name}@dots{}]
  40 Implements a fixup for named silicon errata.  Multiple silicon errata
  41 can be specified by multiple uses of the @option{-msilicon-errata}
  42 option and/or by including the errata names, separated by commas, on
  43 an individual @option{-msilicon-errata} option.  Errata names
  44 currently recognised by the assembler are:
  45
  46 @table @code
  47 @item cpu4
  48 @code{PUSH #4} and @option{PUSH #8} need longer encodings on the
  49 MSP430.  This option is enabled by default, and cannot be disabled.
  50 @item cpu8
  51 Do not set the @code{SP} to an odd value.
  52 @item cpu11
  53 Do not update the @code{SR} and the @code{PC} in the same instruction.
  54 @item cpu12
  55 Do not use the @code{PC} in a @code{CMP} or @code{BIT} instruction.
  56 @item cpu13
  57 Do not use an arithmetic instruction to modify the @code{SR}.
  58 @item cpu19
  59 Insert @code{NOP} after @code{CPUOFF}.
  60 @end table
  61
  62 @item -msilicon-errata-warn=@var{name}[,@var{name}@dots{}]
  63 Like the @option{-msilicon-errata} option except that instead of
  64 fixing the specified errata, a warning message is issued instead.
  65 This option can be used alongside @option{-msilicon-errata} to
  66 generate messages whenever a problem is fixed, or on its own in order
  67 to inspect code for potential problems.
  68
  69 @item -mP
  70 enables polymorph instructions handler.
  71
  72 @item -mQ
  73 enables relaxation at assembly time. DANGEROUS!
  74
  75 @item -ml
  76 indicates that the input uses the large code model.
  77
  78 @item -mn
  79 enables the generation of a NOP instruction following any instruction
  80 that might change the interrupts enabled/disabled state.  The
  81 pipelined nature of the MSP430 core means that any instruction that
  82 changes the interrupt state (@code{EINT}, @code{DINT}, @code{BIC #8,
  83 SR}, @code{BIS #8, SR} or @code{MOV.W <>, SR}) must be
  84 followed by a NOP instruction in order to ensure the correct
  85 processing of interrupts.  By default it is up to the programmer to
  86 supply these NOP instructions, but this command line option enables
  87 the automatic insertion by the assembler, if they are missing.
  88
  89 @item -mN
  90 disables the generation of a NOP instruction following any instruction
  91 that might change the interrupts enabled/disabled state.  This is the
  92 default behaviour.
  93
  94 @item -my
  95 tells the assembler to generate a warning message if a NOP does not
  96 immediately forllow an instruction that enables or disables
  97 interrupts.  This is the default.
  98
  99 Note that this option can be stacked with the @option{-mn} option so
 100 that the assembler will both warn about missing NOP instructions and
 101 then insert them automatically.
 102
 103 @item -mY
 104 disables warnings about missing NOP instructions.
 105
 106 @item -md
 107 mark the object file as one that requires data to copied from ROM to
 108 RAM at execution startup.  Disabled by default.
 109
 110 @end table
 111
 112 @node MSP430 Syntax
 113 @section Syntax
 114 @menu
 115 * MSP430-Macros::               Macros
 116 * MSP430-Chars::                Special Characters
 117 * MSP430-Regs::                 Register Names
 118 * MSP430-Ext::                  Assembler Extensions
 119 @end menu
 120
 121 @node MSP430-Macros
 122 @subsection Macros
 123
 124 @cindex Macros, MSP 430
 125 @cindex MSP 430 macros
 126 The macro syntax used on the MSP 430 is like that described in the MSP
 127 430 Family Assembler Specification.  Normal @code{@value{AS}}
 128 macros should still work.
 129
 130 Additional built-in macros are:
 131
 132 @table @code
 133
 134 @item llo(exp)
 135 Extracts least significant word from 32-bit expression 'exp'.
 136
 137 @item lhi(exp)
 138 Extracts most significant word from 32-bit expression 'exp'.
 139
 140 @item hlo(exp)
 141 Extracts 3rd word from 64-bit expression 'exp'.
 142
 143 @item   hhi(exp)
 144 Extracts 4rd word from 64-bit expression 'exp'.
 145
 146 @end table
 147
 148 They normally being used as an immediate source operand.
 149 @smallexample
 150     mov #llo(1), r10    ;       == mov  #1, r10
 151     mov #lhi(1), r10    ;       == mov  #0, r10
 152 @end smallexample
 153
 154 @node MSP430-Chars
 155 @subsection Special Characters
 156
 157 @cindex line comment character, MSP 430
 158 @cindex MSP 430 line comment character
 159 A semicolon (@samp{;}) appearing anywhere on a line starts a comment
 160 that extends to the end of that line.
 161
 162 If a @samp{#} appears as the first character of a line then the whole
 163 line is treated as a comment, but it can also be a logical line number
 164 directive (@pxref{Comments}) or a preprocessor control command
 165 (@pxref{Preprocessing}).
 166
 167 @cindex line separator, MSP 430
 168 @cindex statement separator, MSP 430
 169 @cindex MSP 430 line separator
 170 Multiple statements can appear on the same line provided that they are
 171 separated by the @samp{@{} character.
 172
 173 @cindex identifiers, MSP 430
 174 @cindex MSP 430 identifiers
 175 The character @samp{$} in jump instructions indicates current location and
 176 implemented only for TI syntax compatibility.
 177
 178 @node MSP430-Regs
 179 @subsection Register Names
 180
 181 @cindex MSP 430 register names
 182 @cindex register names, MSP 430
 183 General-purpose registers are represented by predefined symbols of the
 184 form @samp{r@var{N}} (for global registers), where @var{N} represents
 185 a number between @code{0} and @code{15}.  The leading
 186 letters may be in either upper or lower case; for example, @samp{r13}
 187 and @samp{R7} are both valid register names.
 188
 189 @cindex special purpose registers, MSP 430
 190 Register names @samp{PC}, @samp{SP} and @samp{SR} cannot be used as register names
 191 and will be treated as variables. Use @samp{r0}, @samp{r1}, and @samp{r2} instead.
 192
 193
 194 @node MSP430-Ext
 195 @subsection Assembler Extensions
 196 @cindex MSP430 Assembler Extensions
 197
 198 @table @code
 199
 200 @item @@rN
 201 As destination operand being treated as @samp{0(rn)}
 202
 203 @item 0(rN)
 204 As source operand being treated as @samp{@@rn}
 205
 206 @item jCOND +N
 207 Skips next N bytes followed by jump instruction and equivalent to
 208 @samp{jCOND $+N+2}
 209
 210 @end table
 211
 212 Also, there are some instructions, which cannot be found in other assemblers.
 213 These are branch instructions, which has different opcodes upon jump distance.
 214 They all got PC relative addressing mode.
 215
 216 @table @code
 217 @item   beq label
 218 A polymorph instruction which is @samp{jeq label} in case if jump distance
 219 within allowed range for cpu's jump instruction. If not, this unrolls into
 220 a sequence of
 221 @smallexample
 222   jne $+6
 223   br  label
 224 @end smallexample
 225
 226 @item bne label
 227 A polymorph instruction which is @samp{jne label} or @samp{jeq +4; br label}
 228
 229 @item blt label
 230 A polymorph instruction which is @samp{jl label} or @samp{jge +4; br label}
 231
 232 @item bltn label
 233 A polymorph instruction which is @samp{jn label} or @samp{jn +2; jmp +4; br label}
 234
 235 @item bltu label
 236 A polymorph instruction which is @samp{jlo label} or @samp{jhs +2; br label}
 237
 238 @item bge label
 239 A polymorph instruction which is @samp{jge label} or @samp{jl +4; br label}
 240
 241 @item bgeu label
 242 A polymorph instruction which is @samp{jhs label} or @samp{jlo +4; br label}
 243
 244 @item bgt label
 245 A polymorph instruction which is @samp{jeq +2; jge label} or @samp{jeq +6; jl  +4; br label}
 246
 247 @item bgtu label
 248 A polymorph instruction which is @samp{jeq +2; jhs label} or @samp{jeq +6; jlo +4; br label}
 249
 250 @item bleu label
 251 A polymorph instruction which is @samp{jeq label; jlo label} or @samp{jeq +2; jhs +4; br label}
 252
 253 @item ble label
 254 A polymorph instruction which is @samp{jeq label; jl  label} or @samp{jeq +2; jge +4; br label}
 255
 256 @item jump label
 257 A polymorph instruction which is @samp{jmp label} or @samp{br label}
 258 @end table
 259
 260
 261 @node MSP430 Floating Point
 262 @section Floating Point
 263
 264 @cindex floating point, MSP 430 (@sc{ieee})
 265 @cindex MSP 430 floating point (@sc{ieee})
 266 The MSP 430 family uses @sc{ieee} 32-bit floating-point numbers.
 267
 268 @node MSP430 Directives
 269 @section MSP 430 Machine Directives
 270
 271 @cindex machine directives, MSP 430
 272 @cindex MSP 430 machine directives
 273 @table @code
 274 @cindex @code{file} directive, MSP 430
 275 @item .file
 276 This directive is ignored; it is accepted for compatibility with other
 277 MSP 430 assemblers.
 278
 279 @quotation
 280 @emph{Warning:} in other versions of the @sc{gnu} assembler, @code{.file} is
 281 used for the directive called @code{.app-file} in the MSP 430 support.
 282 @end quotation
 283
 284 @cindex @code{line} directive, MSP 430
 285 @item .line
 286 This directive is ignored; it is accepted for compatibility with other
 287 MSP 430 assemblers.
 288
 289 @cindex @code{arch} directive, MSP 430
 290 @item .arch
 291 Sets the target microcontroller in the same way as the @option{-mmcu}
 292 command line option.
 293
 294 @cindex @code{cpu} directive, MSP 430
 295 @item .cpu
 296 Sets the target architecture in the same way as the @option{-mcpu}
 297 command line option.
 298
 299 @cindex @code{profiler} directive, MSP 430
 300 @item .profiler
 301 This directive instructs assembler to add new profile entry to the object file.
 302
 303 @cindex @code{refsym} directive, MSP 430
 304 @item .refsym
 305 This directive instructs assembler to add an undefined reference to
 306 the symbol following the directive.  The maximum symbol name length is
 307 1023 characters.  No relocation is created for this symbol; it will
 308 exist purely for pulling in object files from archives.  Note that
 309 this reloc is not sufficient to prevent garbage collection; use a
 310 KEEP() directive in the linker file to preserve such objects.
 311
 312 @end table
 313
 314 @node MSP430 Opcodes
 315 @section Opcodes
 316
 317 @cindex MSP 430 opcodes
 318 @cindex opcodes for MSP 430
 319 @code{@value{AS}} implements all the standard MSP 430 opcodes.  No
 320 additional pseudo-instructions are needed on this family.
 321
 322 For information on the 430 machine instruction set, see @cite{MSP430
 323 User's Manual, document slau049d}, Texas Instrument, Inc.
 324
 325 @node MSP430 Profiling Capability
 326 @section Profiling Capability
 327
 328 @cindex MSP 430 profiling capability
 329 @cindex profiling capability for MSP 430
 330 It is a performance hit to use gcc's profiling approach for this tiny target.
 331 Even more -- jtag hardware facility does not perform any profiling functions.
 332 However we've got gdb's built-in simulator where we can do anything.
 333
 334 We define new section @samp{.profiler} which holds all profiling information.
 335 We define new pseudo operation @samp{.profiler} which will instruct assembler to
 336 add new profile entry to the object file. Profile should take place at the
 337 present address.
 338
 339 Pseudo operation format:
 340
 341 @samp{.profiler flags,function_to_profile [, cycle_corrector, extra]}
 342
 343
 344 where:
 345
 346 @table @code
 347
 348 @table @code
 349
 350 @samp{flags} is a combination of the following characters:
 351
 352 @item  s
 353 function entry
 354 @item  x
 355 function exit
 356 @item  i
 357 function is in init section
 358 @item  f
 359 function is in fini section
 360 @item  l
 361 library call
 362 @item  c
 363 libc standard call
 364 @item  d
 365 stack value demand
 366 @item  I
 367 interrupt service routine
 368 @item  P
 369 prologue start
 370 @item  p
 371 prologue end
 372 @item  E
 373 epilogue start
 374 @item  e
 375 epilogue end
 376 @item  j
 377 long jump / sjlj unwind
 378 @item  a
 379 an arbitrary code fragment
 380 @item t
 381 extra parameter saved (a constant value like frame size)
 382 @end table
 383
 384 @item function_to_profile
 385 a function address
 386 @item cycle_corrector
 387 a value which should be added to the cycle counter, zero if omitted.
 388 @item extra
 389 any extra parameter, zero if omitted.
 390
 391 @end table
 392
 393 For example:
 394 @smallexample
 395 .global fxx
 396 .type fxx,@@function
 397 fxx:
 398 .LFrameOffset_fxx=0x08
 399 .profiler "scdP", fxx     ; function entry.
 400                           ; we also demand stack value to be saved
 401   push r11
 402   push r10
 403   push r9
 404   push r8
 405 .profiler "cdpt",fxx,0, .LFrameOffset_fxx  ; check stack value at this point
 406                                           ; (this is a prologue end)
 407                                           ; note, that spare var filled with
 408                                           ; the farme size
 409   mov r15,r8
 410 ...
 411 .profiler cdE,fxx         ; check stack
 412   pop r8
 413   pop r9
 414   pop r10
 415   pop r11
 416 .profiler xcde,fxx,3      ; exit adds 3 to the cycle counter
 417   ret                     ; cause 'ret' insn takes 3 cycles
 418 @end smallexample