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

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