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