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