gas/doc/c-msp430.texi

   1 @c Copyright (C) 2002-2021 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 follow 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 @item -mdata-region=@var{region}
 111 Select the region data will be placed in.
 112 Region placement is performed by the compiler and linker.  The only effect this
 113 option will have on the assembler is that if @var{upper} or @var{either} is
 114 selected, then the symbols to initialise high data and bss will be defined.
 115 Valid @var{region} values are:
 116 @table @code
 117 @item none
 118 @item lower
 119 @item upper
 120 @item either
 121 @end table
 122
 123 @end table
 124
 125 @node MSP430 Syntax
 126 @section Syntax
 127 @menu
 128 * MSP430-Macros::               Macros
 129 * MSP430-Chars::                Special Characters
 130 * MSP430-Regs::                 Register Names
 131 * MSP430-Ext::                  Assembler Extensions
 132 @end menu
 133
 134 @node MSP430-Macros
 135 @subsection Macros
 136
 137 @cindex Macros, MSP 430
 138 @cindex MSP 430 macros
 139 The macro syntax used on the MSP 430 is like that described in the MSP
 140 430 Family Assembler Specification.  Normal @code{@value{AS}}
 141 macros should still work.
 142
 143 Additional built-in macros are:
 144
 145 @table @code
 146
 147 @item llo(exp)
 148 Extracts least significant word from 32-bit expression 'exp'.
 149
 150 @item lhi(exp)
 151 Extracts most significant word from 32-bit expression 'exp'.
 152
 153 @item hlo(exp)
 154 Extracts 3rd word from 64-bit expression 'exp'.
 155
 156 @item   hhi(exp)
 157 Extracts 4rd word from 64-bit expression 'exp'.
 158
 159 @end table
 160
 161 They normally being used as an immediate source operand.
 162 @smallexample
 163     mov #llo(1), r10    ;       == mov  #1, r10
 164     mov #lhi(1), r10    ;       == mov  #0, r10
 165 @end smallexample
 166
 167 @node MSP430-Chars
 168 @subsection Special Characters
 169
 170 @cindex line comment character, MSP 430
 171 @cindex MSP 430 line comment character
 172 A semicolon (@samp{;}) appearing anywhere on a line starts a comment
 173 that extends to the end of that line.
 174
 175 If a @samp{#} appears as the first character of a line then the whole
 176 line is treated as a comment, but it can also be a logical line number
 177 directive (@pxref{Comments}) or a preprocessor control command
 178 (@pxref{Preprocessing}).
 179
 180 @cindex line separator, MSP 430
 181 @cindex statement separator, MSP 430
 182 @cindex MSP 430 line separator
 183 Multiple statements can appear on the same line provided that they are
 184 separated by the @samp{@{} character.
 185
 186 @cindex identifiers, MSP 430
 187 @cindex MSP 430 identifiers
 188 The character @samp{$} in jump instructions indicates current location and
 189 implemented only for TI syntax compatibility.
 190
 191 @node MSP430-Regs
 192 @subsection Register Names
 193
 194 @cindex MSP 430 register names
 195 @cindex register names, MSP 430
 196 General-purpose registers are represented by predefined symbols of the
 197 form @samp{r@var{N}} (for global registers), where @var{N} represents
 198 a number between @code{0} and @code{15}.  The leading
 199 letters may be in either upper or lower case; for example, @samp{r13}
 200 and @samp{R7} are both valid register names.
 201
 202 @cindex special purpose registers, MSP 430
 203 Register names @samp{PC}, @samp{SP} and @samp{SR} cannot be used as register names
 204 and will be treated as variables. Use @samp{r0}, @samp{r1}, and @samp{r2} instead.
 205
 206
 207 @node MSP430-Ext
 208 @subsection Assembler Extensions
 209 @cindex MSP430 Assembler Extensions
 210
 211 @table @code
 212
 213 @item @@rN
 214 As destination operand being treated as @samp{0(rn)}
 215
 216 @item 0(rN)
 217 As source operand being treated as @samp{@@rn}
 218
 219 @item jCOND +N
 220 Skips next N bytes followed by jump instruction and equivalent to
 221 @samp{jCOND $+N+2}
 222
 223 @end table
 224
 225 Also, there are some instructions, which cannot be found in other assemblers.
 226 These are branch instructions, which has different opcodes upon jump distance.
 227 They all got PC relative addressing mode.
 228
 229 @table @code
 230 @item   beq label
 231 A polymorph instruction which is @samp{jeq label} in case if jump distance
 232 within allowed range for cpu's jump instruction. If not, this unrolls into
 233 a sequence of
 234 @smallexample
 235   jne $+6
 236   br  label
 237 @end smallexample
 238
 239 @item bne label
 240 A polymorph instruction which is @samp{jne label} or @samp{jeq +4; br label}
 241
 242 @item blt label
 243 A polymorph instruction which is @samp{jl label} or @samp{jge +4; br label}
 244
 245 @item bltn label
 246 A polymorph instruction which is @samp{jn label} or @samp{jn +2; jmp +4; br label}
 247
 248 @item bltu label
 249 A polymorph instruction which is @samp{jlo label} or @samp{jhs +2; br label}
 250
 251 @item bge label
 252 A polymorph instruction which is @samp{jge label} or @samp{jl +4; br label}
 253
 254 @item bgeu label
 255 A polymorph instruction which is @samp{jhs label} or @samp{jlo +4; br label}
 256
 257 @item bgt label
 258 A polymorph instruction which is @samp{jeq +2; jge label} or @samp{jeq +6; jl  +4; br label}
 259
 260 @item bgtu label
 261 A polymorph instruction which is @samp{jeq +2; jhs label} or @samp{jeq +6; jlo +4; br label}
 262
 263 @item bleu label
 264 A polymorph instruction which is @samp{jeq label; jlo label} or @samp{jeq +2; jhs +4; br label}
 265
 266 @item ble label
 267 A polymorph instruction which is @samp{jeq label; jl  label} or @samp{jeq +2; jge +4; br label}
 268
 269 @item jump label
 270 A polymorph instruction which is @samp{jmp label} or @samp{br label}
 271 @end table
 272
 273
 274 @node MSP430 Floating Point
 275 @section Floating Point
 276
 277 @cindex floating point, MSP 430 (@sc{ieee})
 278 @cindex MSP 430 floating point (@sc{ieee})
 279 The MSP 430 family uses @sc{ieee} 32-bit floating-point numbers.
 280
 281 @node MSP430 Directives
 282 @section MSP 430 Machine Directives
 283
 284 @cindex machine directives, MSP 430
 285 @cindex MSP 430 machine directives
 286 @table @code
 287 @cindex @code{file} directive, MSP 430
 288 @item .file
 289 This directive is ignored; it is accepted for compatibility with other
 290 MSP 430 assemblers.
 291
 292 @quotation
 293 @emph{Warning:} in other versions of the @sc{gnu} assembler, @code{.file} is
 294 used for the directive called @code{.app-file} in the MSP 430 support.
 295 @end quotation
 296
 297 @cindex @code{line} directive, MSP 430
 298 @item .line
 299 This directive is ignored; it is accepted for compatibility with other
 300 MSP 430 assemblers.
 301
 302 @cindex @code{arch} directive, MSP 430
 303 @item .arch
 304 Sets the target microcontroller in the same way as the @option{-mmcu}
 305 command-line option.
 306
 307 @cindex @code{cpu} directive, MSP 430
 308 @item .cpu
 309 Sets the target architecture in the same way as the @option{-mcpu}
 310 command-line option.
 311
 312 @cindex @code{profiler} directive, MSP 430
 313 @item .profiler
 314 This directive instructs assembler to add new profile entry to the object file.
 315
 316 @cindex @code{refsym} directive, MSP 430
 317 @item .refsym
 318 This directive instructs assembler to add an undefined reference to
 319 the symbol following the directive.  The maximum symbol name length is
 320 1023 characters.  No relocation is created for this symbol; it will
 321 exist purely for pulling in object files from archives.  Note that
 322 this reloc is not sufficient to prevent garbage collection; use a
 323 KEEP() directive in the linker file to preserve such objects.
 324
 325 @cindex @code{mspabi_attribute} directive, MSP430
 326 @item .mspabi_attribute
 327 This directive tells the assembler what the MSPABI build attributes for this
 328 file are.  This is used for validating the command line options passed to
 329 the assembler against the options the original source file was compiled with.
 330 The expected format is:
 331 @samp{.mspabi_attribute tag_name, tag_value}
 332 For example, to set the tag @code{OFBA_MSPABI_Tag_ISA} to @code{MSP430X}:
 333 @samp{.mspabi_attribute 4, 2}
 334
 335 See the @cite{MSP430 EABI, document slaa534} for the details on tag names and
 336 values.
 337 @end table
 338
 339 @node MSP430 Opcodes
 340 @section Opcodes
 341
 342 @cindex MSP 430 opcodes
 343 @cindex opcodes for MSP 430
 344 @code{@value{AS}} implements all the standard MSP 430 opcodes.  No
 345 additional pseudo-instructions are needed on this family.
 346
 347 For information on the 430 machine instruction set, see @cite{MSP430
 348 User's Manual, document slau049d}, Texas Instrument, Inc.
 349
 350 @node MSP430 Profiling Capability
 351 @section Profiling Capability
 352
 353 @cindex MSP 430 profiling capability
 354 @cindex profiling capability for MSP 430
 355 It is a performance hit to use gcc's profiling approach for this tiny target.
 356 Even more -- jtag hardware facility does not perform any profiling functions.
 357 However we've got gdb's built-in simulator where we can do anything.
 358
 359 We define new section @samp{.profiler} which holds all profiling information.
 360 We define new pseudo operation @samp{.profiler} which will instruct assembler to
 361 add new profile entry to the object file. Profile should take place at the
 362 present address.
 363
 364 Pseudo operation format:
 365
 366 @samp{.profiler flags,function_to_profile [, cycle_corrector, extra]}
 367
 368
 369 where:
 370
 371 @table @code
 372
 373 @table @code
 374
 375 @samp{flags} is a combination of the following characters:
 376
 377 @item  s
 378 function entry
 379 @item  x
 380 function exit
 381 @item  i
 382 function is in init section
 383 @item  f
 384 function is in fini section
 385 @item  l
 386 library call
 387 @item  c
 388 libc standard call
 389 @item  d
 390 stack value demand
 391 @item  I
 392 interrupt service routine
 393 @item  P
 394 prologue start
 395 @item  p
 396 prologue end
 397 @item  E
 398 epilogue start
 399 @item  e
 400 epilogue end
 401 @item  j
 402 long jump / sjlj unwind
 403 @item  a
 404 an arbitrary code fragment
 405 @item t
 406 extra parameter saved (a constant value like frame size)
 407 @end table
 408
 409 @item function_to_profile
 410 a function address
 411 @item cycle_corrector
 412 a value which should be added to the cycle counter, zero if omitted.
 413 @item extra
 414 any extra parameter, zero if omitted.
 415
 416 @end table
 417
 418 For example:
 419 @smallexample
 420 .global fxx
 421 .type fxx,@@function
 422 fxx:
 423 .LFrameOffset_fxx=0x08
 424 .profiler "scdP", fxx     ; function entry.
 425                           ; we also demand stack value to be saved
 426   push r11
 427   push r10
 428   push r9
 429   push r8
 430 .profiler "cdpt",fxx,0, .LFrameOffset_fxx  ; check stack value at this point
 431                                           ; (this is a prologue end)
 432                                           ; note, that spare var filled with
 433                                           ; the farme size
 434   mov r15,r8
 435 ...
 436 .profiler cdE,fxx         ; check stack
 437   pop r8
 438   pop r9
 439   pop r10
 440   pop r11
 441 .profiler xcde,fxx,3      ; exit adds 3 to the cycle counter
 442   ret                     ; cause 'ret' insn takes 3 cycles
 443 @end smallexample