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