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