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