gas/doc/c-msp430.texi

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