Merge branch 'vendor/BINUTILS221'
[dragonfly.git] / contrib / binutils-2.21 / gas / doc / c-tic54x.texi
1 @c Copyright 2000, 2002, 2003, 2006 Free Software Foundation, Inc.
2 @c This is part of the GAS manual.
3 @c For copying conditions, see the file as.texinfo.
4 @c TI TMS320C54X description by Timothy Wall, twall@cygnus.com
5 @ifset GENERIC
6 @page
7 @node TIC54X-Dependent
8 @chapter TIC54X Dependent Features
9 @end ifset
10 @ifclear GENERIC
11 @node Machine Dependencies
12 @chapter TIC54X Dependent Features
13 @end ifclear
14
15 @cindex TIC54X support
16 @menu
17 * TIC54X-Opts::              Command-line Options
18 * TIC54X-Block::             Blocking
19 * TIC54X-Env::               Environment Settings
20 * TIC54X-Constants::         Constants Syntax
21 * TIC54X-Subsyms::           String Substitution
22 * TIC54X-Locals::            Local Label Syntax
23 * TIC54X-Builtins::          Builtin Assembler Math Functions
24 * TIC54X-Ext::               Extended Addressing Support
25 * TIC54X-Directives::        Directives
26 * TIC54X-Macros::            Macro Features
27 * TIC54X-MMRegs::            Memory-mapped Registers
28 @end menu
29
30 @node TIC54X-Opts
31 @section Options
32
33 @cindex options, TIC54X
34 @cindex TIC54X options
35 The TMS320C54X version of @code{@value{AS}} has a few machine-dependent options.
36
37 @cindex @samp{-mfar-mode} option, far-mode
38 @cindex @samp{-mf} option, far-mode
39 You can use the @samp{-mfar-mode} option to enable extended addressing mode.
40 All addresses will be assumed to be > 16 bits, and the appropriate
41 relocation types will be used.  This option is equivalent to using the
42 @samp{.far_mode} directive in the assembly code.  If you do not use the
43 @samp{-mfar-mode} option, all references will be assumed to be 16 bits.  
44 This option may be abbreviated to @samp{-mf}.
45
46 @cindex @samp{-mcpu} option, cpu
47 You can use the @samp{-mcpu} option to specify a particular CPU.
48 This option is equivalent to using the @samp{.version} directive in the
49 assembly code.  For recognized CPU codes, see
50 @xref{TIC54X-Directives,,@code{.version}}.  The default CPU version is
51 @samp{542}.   
52
53 @cindex @samp{-merrors-to-file} option, stderr redirect
54 @cindex @samp{-me} option, stderr redirect
55 You can use the @samp{-merrors-to-file} option to redirect error output
56 to a file (this provided for those deficient environments which don't
57 provide adequate output redirection).  This option may be abbreviated to
58 @samp{-me}. 
59
60 @node TIC54X-Block
61 @section Blocking
62 A blocked section or memory block is guaranteed not to cross the blocking
63 boundary (usually a page, or 128 words) if it is smaller than the
64 blocking size, or to start on a page boundary if it is larger than the
65 blocking size.
66
67 @node TIC54X-Env
68 @section Environment Settings
69
70 @cindex environment settings, TIC54X
71 @cindex @samp{A_DIR} environment variable, TIC54X
72 @cindex @samp{C54XDSP_DIR} environment variable, TIC54X
73 @samp{C54XDSP_DIR} and @samp{A_DIR} are semicolon-separated
74 paths which are added to the list of directories normally searched for
75 source and include files.  @samp{C54XDSP_DIR} will override @samp{A_DIR}.
76
77 @node TIC54X-Constants
78 @section Constants Syntax
79
80 @cindex constants, TIC54X
81 The TIC54X version of @code{@value{AS}} allows the following additional
82 constant formats, using a suffix to indicate the radix:
83 @smallexample
84 @cindex binary constants, TIC54X
85
86 Binary                  @code{000000B, 011000b}
87 Octal                   @code{10Q, 224q}
88 Hexadecimal             @code{45h, 0FH}
89
90 @end smallexample
91
92 @node TIC54X-Subsyms
93 @section String Substitution
94 A subset of allowable symbols (which we'll call subsyms) may be assigned
95 arbitrary string values.  This is roughly equivalent to C preprocessor
96 #define macros.  When @code{@value{AS}} encounters one of these
97 symbols, the symbol is replaced in the input stream by its string value.
98 Subsym names @strong{must} begin with a letter. 
99
100 Subsyms may be defined using the @code{.asg} and @code{.eval} directives
101 (@xref{TIC54X-Directives,,@code{.asg}},
102 @xref{TIC54X-Directives,,@code{.eval}}. 
103
104 Expansion is recursive until a previously encountered symbol is seen, at
105 which point substitution stops.  
106
107 In this example, x is replaced with SYM2; SYM2 is replaced with SYM1, and SYM1
108 is replaced with x.  At this point, x has already been encountered
109 and the substitution stops.
110
111 @smallexample @code
112  .asg   "x",SYM1 
113  .asg   "SYM1",SYM2
114  .asg   "SYM2",x
115  add    x,a             ; final code assembled is "add  x, a"
116 @end smallexample
117
118 Macro parameters are converted to subsyms; a side effect of this is the normal
119 @code{@value{AS}} '\ARG' dereferencing syntax is unnecessary.  Subsyms
120 defined within a macro will have global scope, unless the @code{.var}
121 directive is used to identify the subsym as a local macro variable
122 @pxref{TIC54X-Directives,,@code{.var}}.
123
124 Substitution may be forced in situations where replacement might be
125 ambiguous by placing colons on either side of the subsym.  The following
126 code: 
127
128 @smallexample @code
129  .eval  "10",x
130 LAB:X:  add     #x, a
131 @end smallexample
132
133 When assembled becomes:
134
135 @smallexample @code
136 LAB10  add     #10, a
137 @end smallexample
138
139 Smaller parts of the string assigned to a subsym may be accessed with
140 the following syntax:
141
142 @table @code
143 @item @code{:@var{symbol}(@var{char_index}):}
144 Evaluates to a single-character string, the character at @var{char_index}.
145 @item @code{:@var{symbol}(@var{start},@var{length}):}
146 Evaluates to a substring of @var{symbol} beginning at @var{start} with
147 length @var{length}.
148 @end table
149
150 @node TIC54X-Locals
151 @section Local Labels
152 Local labels may be defined in two ways:
153
154 @itemize @bullet
155 @item
156 $N, where N is a decimal number between 0 and 9
157 @item
158 LABEL?, where LABEL is any legal symbol name.  
159 @end itemize
160
161 Local labels thus defined may be redefined or automatically generated.
162 The scope of a local label is based on when it may be undefined or reset.
163 This happens when one of the following situations is encountered:
164
165 @itemize @bullet
166 @item
167 .newblock directive @pxref{TIC54X-Directives,,@code{.newblock}}
168 @item
169 The current section is changed (.sect, .text, or .data)
170 @item
171 Entering or leaving an included file
172 @item
173 The macro scope where the label was defined is exited
174 @end itemize
175
176 @node TIC54X-Builtins
177 @section Math Builtins
178
179 @cindex math builtins, TIC54X
180 @cindex TIC54X builtin math functions
181 @cindex builtin math functions, TIC54X
182
183 The following built-in functions may be used to generate a
184 floating-point value.  All return a floating-point value except
185 @samp{$cvi}, @samp{$int}, and @samp{$sgn}, which return an integer
186 value. 
187
188 @table @code
189 @cindex @code{$acos} math builtin, TIC54X
190 @item @code{$acos(@var{expr})}
191 Returns the floating point arccosine of @var{expr}.
192
193 @cindex @code{$asin} math builtin, TIC54X
194 @item @code{$asin(@var{expr})}
195 Returns the floating point arcsine of @var{expr}.
196
197 @cindex @code{$atan} math builtin, TIC54X
198 @item @code{$atan(@var{expr})}
199 Returns the floating point arctangent of @var{expr}.
200
201 @cindex @code{$atan2} math builtin, TIC54X
202 @item @code{$atan2(@var{expr1},@var{expr2})}
203 Returns the floating point arctangent of @var{expr1} / @var{expr2}.
204
205 @cindex @code{$ceil} math builtin, TIC54X
206 @item @code{$ceil(@var{expr})}
207 Returns the smallest integer not less than @var{expr} as floating point.
208
209 @cindex @code{$cosh} math builtin, TIC54X
210 @item @code{$cosh(@var{expr})}
211 Returns the floating point hyperbolic cosine of @var{expr}.
212
213 @cindex @code{$cos} math builtin, TIC54X
214 @item @code{$cos(@var{expr})}
215 Returns the floating point cosine of @var{expr}.
216
217 @cindex @code{$cvf} math builtin, TIC54X
218 @item @code{$cvf(@var{expr})}
219 Returns the integer value @var{expr} converted to floating-point.
220
221 @cindex @code{$cvi} math builtin, TIC54X
222 @item @code{$cvi(@var{expr})}
223 Returns the floating point value @var{expr} converted to integer.
224
225 @cindex @code{$exp} math builtin, TIC54X
226 @item @code{$exp(@var{expr})}
227 Returns the floating point value e ^ @var{expr}.
228
229 @cindex @code{$fabs} math builtin, TIC54X
230 @item @code{$fabs(@var{expr})}
231 Returns the floating point absolute value of @var{expr}.
232
233 @cindex @code{$floor} math builtin, TIC54X
234 @item @code{$floor(@var{expr})}
235 Returns the largest integer that is not greater than @var{expr} as
236 floating point.
237
238 @cindex @code{$fmod} math builtin, TIC54X
239 @item @code{$fmod(@var{expr1},@var{expr2})}
240 Returns the floating point remainder of @var{expr1} / @var{expr2}.
241
242 @cindex @code{$int} math builtin, TIC54X
243 @item @code{$int(@var{expr})}
244 Returns 1 if @var{expr} evaluates to an integer, zero otherwise.
245
246 @cindex @code{$ldexp} math builtin, TIC54X
247 @item @code{$ldexp(@var{expr1},@var{expr2})}
248 Returns the floating point value @var{expr1} * 2 ^ @var{expr2}.
249
250 @cindex @code{$log10} math builtin, TIC54X
251 @item @code{$log10(@var{expr})}
252 Returns the base 10 logarithm of @var{expr}.
253
254 @cindex @code{$log} math builtin, TIC54X
255 @item @code{$log(@var{expr})}
256 Returns the natural logarithm of @var{expr}.
257
258 @cindex @code{$max} math builtin, TIC54X
259 @item @code{$max(@var{expr1},@var{expr2})}
260 Returns the floating point maximum of @var{expr1} and @var{expr2}.
261
262 @cindex @code{$min} math builtin, TIC54X
263 @item @code{$min(@var{expr1},@var{expr2})}
264 Returns the floating point minimum of @var{expr1} and @var{expr2}.
265
266 @cindex @code{$pow} math builtin, TIC54X
267 @item @code{$pow(@var{expr1},@var{expr2})}
268 Returns the floating point value @var{expr1} ^ @var{expr2}.
269
270 @cindex @code{$round} math builtin, TIC54X
271 @item @code{$round(@var{expr})}
272 Returns the nearest integer to @var{expr} as a floating point number.
273
274 @cindex @code{$sgn} math builtin, TIC54X
275 @item @code{$sgn(@var{expr})}
276 Returns -1, 0, or 1 based on the sign of @var{expr}.
277
278 @cindex @code{$sin} math builtin, TIC54X
279 @item @code{$sin(@var{expr})}
280 Returns the floating point sine of @var{expr}.
281
282 @cindex @code{$sinh} math builtin, TIC54X
283 @item @code{$sinh(@var{expr})}
284 Returns the floating point hyperbolic sine of @var{expr}.
285
286 @cindex @code{$sqrt} math builtin, TIC54X
287 @item @code{$sqrt(@var{expr})}
288 Returns the floating point square root of @var{expr}.
289
290 @cindex @code{$tan} math builtin, TIC54X
291 @item @code{$tan(@var{expr})}
292 Returns the floating point tangent of @var{expr}.
293
294 @cindex @code{$tanh} math builtin, TIC54X
295 @item @code{$tanh(@var{expr})}
296 Returns the floating point hyperbolic tangent of @var{expr}.
297
298 @cindex @code{$trunc} math builtin, TIC54X
299 @item @code{$trunc(@var{expr})}
300 Returns the integer value of @var{expr} truncated towards zero as
301 floating point.
302
303 @end table
304
305 @node TIC54X-Ext
306 @section Extended Addressing
307 The @code{LDX} pseudo-op is provided for loading the extended addressing bits
308 of a label or address.  For example, if an address @code{_label} resides
309 in extended program memory, the value of @code{_label} may be loaded as
310 follows:
311 @smallexample @code
312  ldx     #_label,16,a    ; loads extended bits of _label
313  or      #_label,a       ; loads lower 16 bits of _label
314  bacc    a               ; full address is in accumulator A
315 @end smallexample
316
317 @node TIC54X-Directives
318 @section Directives
319
320 @cindex machine directives, TIC54X
321 @cindex TIC54X machine directives
322
323 @table @code
324
325 @cindex @code{align} directive, TIC54X
326 @cindex @code{even} directive, TIC54X
327 @item .align [@var{size}]
328 @itemx .even
329 Align the section program counter on the next boundary, based on
330 @var{size}.  @var{size} may be any power of 2.  @code{.even} is
331 equivalent to @code{.align} with a @var{size} of 2.
332 @table @code
333 @item 1
334 Align SPC to word boundary
335 @item 2
336 Align SPC to longword boundary (same as .even)
337 @item 128       
338 Align SPC to page boundary
339 @end table
340
341 @cindex @code{asg} directive, TIC54X
342 @item .asg @var{string}, @var{name}
343 Assign @var{name} the string @var{string}.  String replacement is
344 performed on @var{string} before assignment.
345
346 @cindex @code{eval} directive, TIC54X
347 @itemx .eval @var{string}, @var{name}
348 Evaluate the contents of string @var{string} and assign the result as a
349 string to the subsym @var{name}.  String replacement is performed on
350 @var{string} before assignment. 
351
352 @cindex @code{bss} directive, TIC54X
353 @item .bss @var{symbol}, @var{size} [, [@var{blocking_flag}] [,@var{alignment_flag}]]
354 Reserve space for @var{symbol} in the .bss section.  @var{size} is in
355 words.  If present, @var{blocking_flag} indicates the allocated space
356 should be aligned on a page boundary if it would otherwise cross a page
357 boundary.  If present, @var{alignment_flag} causes the assembler to
358 allocate @var{size} on a long word boundary.
359
360 @cindex @code{byte} directive, TIC54X
361 @cindex @code{ubyte} directive, TIC54X
362 @cindex @code{char} directive, TIC54X
363 @cindex @code{uchar} directive, TIC54X
364 @item .byte @var{value} [,...,@var{value_n}]
365 @itemx .ubyte @var{value} [,...,@var{value_n}]
366 @itemx .char @var{value} [,...,@var{value_n}]
367 @itemx .uchar @var{value} [,...,@var{value_n}]
368 Place one or more bytes into consecutive words of the current section.
369 The upper 8 bits of each word is zero-filled.  If a label is used, it
370 points to the word allocated for the first byte encountered.
371
372 @cindex @code{clink} directive, TIC54X
373 @item .clink ["@var{section_name}"]
374 Set STYP_CLINK flag for this section, which indicates to the linker that
375 if no symbols from this section are referenced, the section should not
376 be included in the link.  If @var{section_name} is omitted, the current
377 section is used.
378
379 @cindex @code{c_mode} directive, TIC54X
380 @item .c_mode
381 TBD.
382
383 @cindex @code{copy} directive, TIC54X
384 @item .copy "@var{filename}" | @var{filename}
385 @itemx .include "@var{filename}" | @var{filename}
386 Read source statements from @var{filename}.  The normal include search
387 path is used.  Normally .copy will cause statements from the included
388 file to be printed in the assembly listing and .include will not, but
389 this distinction is not currently implemented.
390
391 @cindex @code{data} directive, TIC54X
392 @item .data
393 Begin assembling code into the .data section.
394
395 @cindex @code{double} directive, TIC54X
396 @cindex @code{ldouble} directive, TIC54X
397 @cindex @code{float} directive, TIC54X
398 @cindex @code{xfloat} directive, TIC54X
399 @item .double @var{value} [,...,@var{value_n}]
400 @itemx .ldouble @var{value} [,...,@var{value_n}]
401 @itemx .float @var{value} [,...,@var{value_n}]
402 @itemx .xfloat @var{value} [,...,@var{value_n}]
403 Place an IEEE single-precision floating-point representation of one or
404 more floating-point values into the current section.  All but
405 @code{.xfloat} align the result on a longword boundary.  Values are
406 stored most-significant word first. 
407
408 @cindex @code{drlist} directive, TIC54X
409 @cindex @code{drnolist} directive, TIC54X
410 @item .drlist
411 @itemx .drnolist
412 Control printing of directives to the listing file.  Ignored.
413
414 @cindex @code{emsg} directive, TIC54X
415 @cindex @code{mmsg} directive, TIC54X
416 @cindex @code{wmsg} directive, TIC54X
417 @item .emsg @var{string}
418 @itemx .mmsg @var{string}
419 @itemx .wmsg @var{string}
420 Emit a user-defined error, message, or warning, respectively.
421
422 @cindex @code{far_mode} directive, TIC54X
423 @item .far_mode
424 Use extended addressing when assembling statements.  This should appear
425 only once per file, and is equivalent to the -mfar-mode option @pxref{TIC54X-Opts,,@code{-mfar-mode}}.
426
427 @cindex @code{fclist} directive, TIC54X
428 @cindex @code{fcnolist} directive, TIC54X
429 @item .fclist
430 @itemx .fcnolist
431 Control printing of false conditional blocks to the listing file.
432
433 @cindex @code{field} directive, TIC54X
434 @item .field @var{value} [,@var{size}]
435 Initialize a bitfield of @var{size} bits in the current section.  If
436 @var{value} is relocatable, then @var{size} must be 16.  @var{size}
437 defaults to 16 bits.  If @var{value} does not fit into @var{size} bits,
438 the value will be truncated.  Successive @code{.field} directives will
439 pack starting at the current word, filling the most significant bits
440 first, and aligning to the start of the next word if the field size does
441 not fit into the space remaining in the current word.  A @code{.align}
442 directive with an operand of 1 will force the next @code{.field}
443 directive to begin packing into a new word.  If a label is used, it
444 points to the word that contains the specified field.
445
446 @cindex @code{global} directive, TIC54X
447 @cindex @code{def} directive, TIC54X
448 @cindex @code{ref} directive, TIC54X
449 @item .global @var{symbol} [,...,@var{symbol_n}]
450 @itemx .def @var{symbol} [,...,@var{symbol_n}]
451 @itemx .ref @var{symbol} [,...,@var{symbol_n}]
452 @code{.def} nominally identifies a symbol defined in the current file
453 and available to other files.  @code{.ref} identifies a symbol used in
454 the current file but defined elsewhere.  Both map to the standard
455 @code{.global} directive.
456
457 @cindex @code{half} directive, TIC54X
458 @cindex @code{uhalf} directive, TIC54X
459 @cindex @code{short} directive, TIC54X
460 @cindex @code{ushort} directive, TIC54X
461 @cindex @code{int} directive, TIC54X
462 @cindex @code{uint} directive, TIC54X
463 @cindex @code{word} directive, TIC54X
464 @cindex @code{uword} directive, TIC54X
465 @item .half @var{value} [,...,@var{value_n}]
466 @itemx .uhalf @var{value} [,...,@var{value_n}]
467 @itemx .short @var{value} [,...,@var{value_n}]
468 @itemx .ushort @var{value} [,...,@var{value_n}]
469 @itemx .int @var{value} [,...,@var{value_n}]
470 @itemx .uint @var{value} [,...,@var{value_n}]
471 @itemx .word @var{value} [,...,@var{value_n}]
472 @itemx .uword @var{value} [,...,@var{value_n}]
473 Place one or more values into consecutive words of the current section.
474 If a label is used, it points to the word allocated for the first value
475 encountered. 
476
477 @cindex @code{label} directive, TIC54X
478 @item .label @var{symbol}
479 Define a special @var{symbol} to refer to the load time address of the
480 current section program counter.
481
482 @cindex @code{length} directive, TIC54X
483 @cindex @code{width} directive, TIC54X
484 @item .length
485 @itemx .width
486 Set the page length and width of the output listing file.  Ignored.
487
488 @cindex @code{list} directive, TIC54X
489 @cindex @code{nolist} directive, TIC54X
490 @item .list
491 @itemx .nolist
492 Control whether the source listing is printed.  Ignored.
493
494 @cindex @code{long} directive, TIC54X
495 @cindex @code{ulong} directive, TIC54X
496 @cindex @code{xlong} directive, TIC54X
497 @item .long @var{value} [,...,@var{value_n}]
498 @itemx .ulong @var{value} [,...,@var{value_n}]
499 @itemx .xlong @var{value} [,...,@var{value_n}]
500 Place one or more 32-bit values into consecutive words in the current
501 section.  The most significant word is stored first.  @code{.long} and
502 @code{.ulong} align the result on a longword boundary; @code{xlong} does
503 not. 
504
505 @cindex @code{loop} directive, TIC54X
506 @cindex @code{break} directive, TIC54X
507 @cindex @code{endloop} directive, TIC54X
508 @item .loop [@var{count}]
509 @itemx .break [@var{condition}]
510 @itemx .endloop
511 Repeatedly assemble a block of code.  @code{.loop} begins the block, and
512 @code{.endloop} marks its termination.  @var{count} defaults to 1024,
513 and indicates the number of times the block should be repeated.
514 @code{.break} terminates the loop so that assembly begins after the
515 @code{.endloop} directive.  The optional @var{condition} will cause the
516 loop to terminate only if it evaluates to zero.
517
518 @cindex @code{macro} directive, TIC54X
519 @cindex @code{endm} directive, TIC54X
520 @item @var{macro_name} .macro [@var{param1}][,...@var{param_n}]
521 @itemx [.mexit]
522 @itemx .endm
523 See the section on macros for more explanation (@xref{TIC54X-Macros}.
524
525 @cindex @code{mlib} directive, TIC54X
526 @item .mlib "@var{filename}" | @var{filename}
527 Load the macro library @var{filename}.  @var{filename} must be an
528 archived library (BFD ar-compatible) of text files, expected to contain
529 only macro definitions.   The standard include search path is used.
530
531 @cindex @code{mlist} directive, TIC54X
532 @cindex @code{mnolist} directive, TIC54X
533 @item .mlist
534 @itemx .mnolist
535 Control whether to include macro and loop block expansions in the
536 listing output.  Ignored.
537
538 @cindex @code{mmregs} directive, TIC54X
539 @item .mmregs
540 Define global symbolic names for the 'c54x registers.  Supposedly
541 equivalent to executing @code{.set} directives for each register with
542 its memory-mapped value, but in reality is provided only for
543 compatibility and does nothing.
544
545 @cindex @code{newblock} directive, TIC54X
546 @item .newblock
547 This directive resets any TIC54X local labels currently defined.  Normal
548 @code{@value{AS}} local labels are unaffected.
549
550 @cindex @code{option} directive, TIC54X
551 @item .option @var{option_list}
552 Set listing options.  Ignored.
553
554 @cindex @code{sblock} directive, TIC54X
555 @item .sblock "@var{section_name}" | @var{section_name} [,"@var{name_n}" | @var{name_n}]
556 Designate @var{section_name} for blocking.  Blocking guarantees that a
557 section will start on a page boundary (128 words) if it would otherwise
558 cross a page boundary.  Only initialized sections may be designated with
559 this directive.  See also @xref{TIC54X-Block}.
560
561 @cindex @code{sect} directive, TIC54X
562 @item .sect "@var{section_name}"
563 Define a named initialized section and make it the current section.
564
565 @cindex @code{set} directive, TIC54X
566 @cindex @code{equ} directive, TIC54X
567 @item @var{symbol} .set "@var{value}"
568 @itemx @var{symbol} .equ "@var{value}"
569 Equate a constant @var{value} to a @var{symbol}, which is placed in the
570 symbol table.  @var{symbol} may not be previously defined.  
571
572 @cindex @code{space} directive, TIC54X
573 @cindex @code{bes} directive, TIC54X
574 @item .space @var{size_in_bits}
575 @itemx .bes @var{size_in_bits}
576 Reserve the given number of bits in the current section and zero-fill
577 them.  If a label is used with @code{.space}, it points to the
578 @strong{first} word reserved.  With @code{.bes}, the label points to the
579 @strong{last} word reserved.
580
581 @cindex @code{sslist} directive, TIC54X
582 @cindex @code{ssnolist} directive, TIC54X
583 @item .sslist
584 @itemx .ssnolist
585 Controls the inclusion of subsym replacement in the listing output.  Ignored.
586
587 @cindex @code{string} directive, TIC54X
588 @cindex @code{pstring} directive, TIC54X
589 @item .string "@var{string}" [,...,"@var{string_n}"]
590 @itemx .pstring "@var{string}" [,...,"@var{string_n}"]
591 Place 8-bit characters from @var{string} into the current section.
592 @code{.string} zero-fills the upper 8 bits of each word, while
593 @code{.pstring} puts two characters into each word, filling the
594 most-significant bits first.  Unused space is zero-filled.  If a label
595 is used, it points to the first word initialized.
596
597 @cindex @code{struct} directive, TIC54X
598 @cindex @code{tag} directive, TIC54X
599 @cindex @code{endstruct} directive, TIC54X
600 @item [@var{stag}] .struct [@var{offset}]
601 @itemx [@var{name_1}] element [@var{count_1}]
602 @itemx [@var{name_2}] element [@var{count_2}]
603 @itemx [@var{tname}] .tag @var{stagx} [@var{tcount}]
604 @itemx ...
605 @itemx [@var{name_n}] element [@var{count_n}]
606 @itemx [@var{ssize}] .endstruct
607 @itemx @var{label} .tag [@var{stag}]
608 Assign symbolic offsets to the elements of a structure.  @var{stag}
609 defines a symbol to use to reference the structure.  @var{offset}
610 indicates a starting value to use for the first element encountered;
611 otherwise it defaults to zero.  Each element can have a named offset,
612 @var{name}, which is a symbol assigned the value of the element's offset
613 into the structure.  If @var{stag} is missing, these become global
614 symbols.  @var{count} adjusts the offset that many times, as if
615 @code{element} were an array.  @code{element} may be one of
616 @code{.byte}, @code{.word}, @code{.long}, @code{.float}, or any
617 equivalent of those, and the structure offset is adjusted accordingly.
618 @code{.field} and @code{.string} are also allowed; the size of
619 @code{.field} is one bit, and @code{.string} is considered to be one
620 word in size.  Only element descriptors, structure/union tags,
621 @code{.align} and conditional assembly directives are allowed within
622 @code{.struct}/@code{.endstruct}.  @code{.align} aligns member offsets
623 to word boundaries only.  @var{ssize}, if provided, will always be
624 assigned the size of the structure.
625
626 The @code{.tag} directive, in addition to being used to define a
627 structure/union element within a structure, may be used to apply a
628 structure to a symbol.  Once applied to @var{label}, the individual
629 structure elements may be applied to @var{label} to produce the desired
630 offsets using @var{label} as the structure base. 
631
632 @cindex @code{tab} directive, TIC54X
633 @item .tab
634 Set the tab size in the output listing.  Ignored.
635
636 @cindex @code{union} directive, TIC54X
637 @cindex @code{tag} directive, TIC54X
638 @cindex @code{endunion} directive, TIC54X
639 @item [@var{utag}] .union 
640 @itemx [@var{name_1}] element [@var{count_1}]
641 @itemx [@var{name_2}] element [@var{count_2}]
642 @itemx [@var{tname}] .tag @var{utagx}[,@var{tcount}]
643 @itemx ...
644 @itemx [@var{name_n}] element [@var{count_n}]
645 @itemx [@var{usize}] .endstruct
646 @itemx @var{label} .tag [@var{utag}]
647 Similar to @code{.struct}, but the offset after each element is reset to
648 zero, and the @var{usize} is set to the maximum of all defined elements.
649 Starting offset for the union is always zero.
650
651 @cindex @code{usect} directive, TIC54X
652 @item [@var{symbol}] .usect "@var{section_name}", @var{size}, [,[@var{blocking_flag}] [,@var{alignment_flag}]]
653 Reserve space for variables in a named, uninitialized section (similar to
654 .bss).  @code{.usect} allows definitions sections independent of .bss.
655 @var{symbol} points to the first location reserved by this allocation.
656 The symbol may be used as a variable name.  @var{size} is the allocated
657 size in words.  @var{blocking_flag} indicates whether to block this
658 section on a page boundary (128 words) (@pxref{TIC54X-Block}).
659 @var{alignment flag} indicates whether the section should be
660 longword-aligned.  
661
662 @cindex @code{var} directive, TIC54X
663 @item .var @var{sym}[,..., @var{sym_n}]
664 Define a subsym to be a local variable within a macro.  See
665 @xref{TIC54X-Macros}. 
666
667 @cindex @code{version} directive, TIC54X
668 @item .version @var{version}
669 Set which processor to build instructions for.  Though the following
670 values are accepted, the op is ignored.
671 @table @code
672 @item 541
673 @itemx 542
674 @itemx 543
675 @itemx 545
676 @itemx 545LP
677 @itemx 546LP
678 @itemx 548
679 @itemx 549
680 @end table
681 @end table
682
683 @node TIC54X-Macros
684 @section Macros
685
686 @cindex TIC54X-specific macros
687 @cindex macros, TIC54X
688 Macros do not require explicit dereferencing of arguments (i.e., \ARG).  
689
690 During macro expansion, the macro parameters are converted to subsyms.
691 If the number of arguments passed the macro invocation exceeds the
692 number of parameters defined, the last parameter is assigned the string
693 equivalent of all remaining arguments.  If fewer arguments are given
694 than parameters, the missing parameters are assigned empty strings.  To
695 include a comma in an argument, you must enclose the argument in quotes.
696
697 @cindex subsym builtins, TIC54X
698 @cindex TIC54X subsym builtins
699 @cindex builtin subsym functions, TIC54X
700 The following built-in subsym functions allow examination of the string
701 value of subsyms (or ordinary strings).  The arguments are strings
702 unless otherwise indicated (subsyms passed as args will be replaced by
703 the strings they represent).
704 @table @code
705 @cindex @code{$symlen} subsym builtin, TIC54X
706 @item @code{$symlen(@var{str})}
707 Returns the length of @var{str}.
708
709 @cindex @code{$symcmp} subsym builtin, TIC54X
710 @item @code{$symcmp(@var{str1},@var{str2})}
711 Returns 0 if @var{str1} == @var{str2}, non-zero otherwise.  
712
713 @cindex @code{$firstch} subsym builtin, TIC54X
714 @item @code{$firstch(@var{str},@var{ch})}
715 Returns index of the first occurrence of character constant @var{ch} in
716 @var{str}. 
717
718 @cindex @code{$lastch} subsym builtin, TIC54X
719 @item @code{$lastch(@var{str},@var{ch})}
720 Returns index of the last occurrence of character constant @var{ch} in
721 @var{str}. 
722
723 @cindex @code{$isdefed} subsym builtin, TIC54X
724 @item @code{$isdefed(@var{symbol})}
725 Returns zero if the symbol @var{symbol} is not in the symbol table,
726 non-zero otherwise.
727
728 @cindex @code{$ismember} subsym builtin, TIC54X
729 @item @code{$ismember(@var{symbol},@var{list})}
730 Assign the first member of comma-separated string @var{list} to
731 @var{symbol}; @var{list} is reassigned the remainder of the list.  Returns
732 zero if @var{list} is a null string.  Both arguments must be subsyms.
733
734 @cindex @code{$iscons} subsym builtin, TIC54X
735 @item @code{$iscons(@var{expr})}
736 Returns 1 if string @var{expr} is binary, 2 if octal, 3 if hexadecimal,
737 4 if a character, 5 if decimal, and zero if not an integer.
738
739 @cindex @code{$isname} subsym builtin, TIC54X
740 @item @code{$isname(@var{name})}
741 Returns 1 if @var{name} is a valid symbol name, zero otherwise.
742
743 @cindex @code{$isreg} subsym builtin, TIC54X
744 @item @code{$isreg(@var{reg})}
745 Returns 1 if @var{reg} is a valid predefined register name (AR0-AR7 only).
746
747 @cindex @code{$structsz} subsym builtin, TIC54X
748 @item @code{$structsz(@var{stag})}
749 Returns the size of the structure or union represented by @var{stag}.
750
751 @cindex @code{$structacc} subsym builtin, TIC54X
752 @item @code{$structacc(@var{stag})}
753 Returns the reference point of the structure or union represented by
754 @var{stag}.   Always returns zero.
755
756 @end table
757
758 @node TIC54X-MMRegs
759 @section Memory-mapped Registers
760
761 @cindex TIC54X memory-mapped registers
762 @cindex registers, TIC54X memory-mapped
763 @cindex memory-mapped registers, TIC54X
764 The following symbols are recognized as memory-mapped registers:
765
766 @table @code
767 @end table