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 @cindex @code{refsym} directive, MSP 430
 267 @item .refsym
 268 This directive instructs assembler to add an undefined reference to
 269 the symbol following the directive.  The maximum symbol name length is
 270 1023 characters.  No relocation is created for this symbol; it will
 271 exist purely for pulling in object files from archives.  Note that
 272 this reloc is not sufficient to prevent garbage collection; use a
 273 KEEP() directive in the linker file to preserve such objects.
 274
 275 @end table
 276
 277 @node MSP430 Opcodes
 278 @section Opcodes
 279
 280 @cindex MSP 430 opcodes
 281 @cindex opcodes for MSP 430
 282 @code{@value{AS}} implements all the standard MSP 430 opcodes.  No
 283 additional pseudo-instructions are needed on this family.
 284
 285 For information on the 430 machine instruction set, see @cite{MSP430
 286 User's Manual, document slau049d}, Texas Instrument, Inc.
 287
 288 @node MSP430 Profiling Capability
 289 @section Profiling Capability
 290
 291 @cindex MSP 430 profiling capability
 292 @cindex profiling capability for MSP 430
 293 It is a performance hit to use gcc's profiling approach for this tiny target.
 294 Even more -- jtag hardware facility does not perform any profiling functions.
 295 However we've got gdb's built-in simulator where we can do anything.
 296
 297 We define new section @samp{.profiler} which holds all profiling information.
 298 We define new pseudo operation @samp{.profiler} which will instruct assembler to
 299 add new profile entry to the object file. Profile should take place at the
 300 present address.
 301
 302 Pseudo operation format:
 303
 304 @samp{.profiler flags,function_to_profile [, cycle_corrector, extra]}
 305
 306
 307 where:
 308
 309 @table @code
 310
 311 @table @code
 312
 313 @samp{flags} is a combination of the following characters:
 314
 315 @item  s
 316 function entry
 317 @item  x
 318 function exit
 319 @item  i
 320 function is in init section
 321 @item  f
 322 function is in fini section
 323 @item  l
 324 library call
 325 @item  c
 326 libc standard call
 327 @item  d
 328 stack value demand
 329 @item  I
 330 interrupt service routine
 331 @item  P
 332 prologue start
 333 @item  p
 334 prologue end
 335 @item  E
 336 epilogue start
 337 @item  e
 338 epilogue end
 339 @item  j
 340 long jump / sjlj unwind
 341 @item  a
 342 an arbitrary code fragment
 343 @item t
 344 extra parameter saved (a constant value like frame size)
 345 @end table
 346
 347 @item function_to_profile
 348 a function address
 349 @item cycle_corrector
 350 a value which should be added to the cycle counter, zero if omitted.
 351 @item extra
 352 any extra parameter, zero if omitted.
 353
 354 @end table
 355
 356 For example:
 357 @smallexample
 358 .global fxx
 359 .type fxx,@@function
 360 fxx:
 361 .LFrameOffset_fxx=0x08
 362 .profiler "scdP", fxx     ; function entry.
 363                           ; we also demand stack value to be saved
 364   push r11
 365   push r10
 366   push r9
 367   push r8
 368 .profiler "cdpt",fxx,0, .LFrameOffset_fxx  ; check stack value at this point
 369                                           ; (this is a prologue end)
 370                                           ; note, that spare var filled with
 371                                           ; the farme size
 372   mov r15,r8
 373 ...
 374 .profiler cdE,fxx         ; check stack
 375   pop r8
 376   pop r9
 377   pop r10
 378   pop r11
 379 .profiler xcde,fxx,3      ; exit adds 3 to the cycle counter
 380   ret                     ; cause 'ret' insn takes 3 cycles
 381 @end smallexample