gas/doc/c-msp430.texi

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