gas/doc/c-tic54x.texi

   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
  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 * TIC54X-Syntax::            Syntax
  29 @end menu
  30
  31 @node TIC54X-Opts
  32 @section Options
  33
  34 @cindex options, TIC54X
  35 @cindex TIC54X options
  36 The TMS320C54X version of @code{@value{AS}} has a few machine-dependent options.
  37
  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}.
  46
  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}.
  53
  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}.
  60
  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.
  67
  68 @node TIC54X-Env
  69 @section Environment Settings
  70
  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}.
  77
  78 @node TIC54X-Constants
  79 @section Constants Syntax
  80
  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
  86
  87 Binary                  @code{000000B, 011000b}
  88 Octal                   @code{10Q, 224q}
  89 Hexadecimal             @code{45h, 0FH}
  90
  91 @end smallexample
  92
  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.
 100
 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}}.
 104
 105 Expansion is recursive until a previously encountered symbol is seen, at
 106 which point substitution stops.
 107
 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.
 111
 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
 118
 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}}.
 124
 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:
 128
 129 @smallexample
 130  .eval  "10",x
 131 LAB:X:  add     #x, a
 132 @end smallexample
 133
 134 When assembled becomes:
 135
 136 @smallexample
 137 LAB10  add     #10, a
 138 @end smallexample
 139
 140 Smaller parts of the string assigned to a subsym may be accessed with
 141 the following syntax:
 142
 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
 150
 151 @node TIC54X-Locals
 152 @section Local Labels
 153 Local labels may be defined in two ways:
 154
 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
 161
 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:
 165
 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
 176
 177 @node TIC54X-Builtins
 178 @section Math Builtins
 179
 180 @cindex math builtins, TIC54X
 181 @cindex TIC54X builtin math functions
 182 @cindex builtin math functions, TIC54X
 183
 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.
 188
 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}.
 193
 194 @cindex @code{$asin} math builtin, TIC54X
 195 @item @code{$asin(@var{expr})}
 196 Returns the floating point arcsine of @var{expr}.
 197
 198 @cindex @code{$atan} math builtin, TIC54X
 199 @item @code{$atan(@var{expr})}
 200 Returns the floating point arctangent of @var{expr}.
 201
 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}.
 205
 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.
 209
 210 @cindex @code{$cosh} math builtin, TIC54X
 211 @item @code{$cosh(@var{expr})}
 212 Returns the floating point hyperbolic cosine of @var{expr}.
 213
 214 @cindex @code{$cos} math builtin, TIC54X
 215 @item @code{$cos(@var{expr})}
 216 Returns the floating point cosine of @var{expr}.
 217
 218 @cindex @code{$cvf} math builtin, TIC54X
 219 @item @code{$cvf(@var{expr})}
 220 Returns the integer value @var{expr} converted to floating-point.
 221
 222 @cindex @code{$cvi} math builtin, TIC54X
 223 @item @code{$cvi(@var{expr})}
 224 Returns the floating point value @var{expr} converted to integer.
 225
 226 @cindex @code{$exp} math builtin, TIC54X
 227 @item @code{$exp(@var{expr})}
 228 Returns the floating point value e ^ @var{expr}.
 229
 230 @cindex @code{$fabs} math builtin, TIC54X
 231 @item @code{$fabs(@var{expr})}
 232 Returns the floating point absolute value of @var{expr}.
 233
 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.
 238
 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}.
 242
 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.
 246
 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}.
 250
 251 @cindex @code{$log10} math builtin, TIC54X
 252 @item @code{$log10(@var{expr})}
 253 Returns the base 10 logarithm of @var{expr}.
 254
 255 @cindex @code{$log} math builtin, TIC54X
 256 @item @code{$log(@var{expr})}
 257 Returns the natural logarithm of @var{expr}.
 258
 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}.
 262
 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}.
 266
 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}.
 270
 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.
 274
 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}.
 278
 279 @cindex @code{$sin} math builtin, TIC54X
 280 @item @code{$sin(@var{expr})}
 281 Returns the floating point sine of @var{expr}.
 282
 283 @cindex @code{$sinh} math builtin, TIC54X
 284 @item @code{$sinh(@var{expr})}
 285 Returns the floating point hyperbolic sine of @var{expr}.
 286
 287 @cindex @code{$sqrt} math builtin, TIC54X
 288 @item @code{$sqrt(@var{expr})}
 289 Returns the floating point square root of @var{expr}.
 290
 291 @cindex @code{$tan} math builtin, TIC54X
 292 @item @code{$tan(@var{expr})}
 293 Returns the floating point tangent of @var{expr}.
 294
 295 @cindex @code{$tanh} math builtin, TIC54X
 296 @item @code{$tanh(@var{expr})}
 297 Returns the floating point hyperbolic tangent of @var{expr}.
 298
 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.
 303
 304 @end table
 305
 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
 317
 318 @node TIC54X-Directives
 319 @section Directives
 320
 321 @cindex machine directives, TIC54X
 322 @cindex TIC54X machine directives
 323
 324 @table @code
 325
 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
 341
 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.
 346
 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.
 352
 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.
 360
 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.
 372
 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.
 379
 380 @cindex @code{c_mode} directive, TIC54X
 381 @item .c_mode
 382 TBD.
 383
 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.
 391
 392 @cindex @code{data} directive, TIC54X
 393 @item .data
 394 Begin assembling code into the .data section.
 395
 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.
 408
 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.
 414
 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.
 422
 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}}.
 427
 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.
 433
 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.
 446
 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.
 457
 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.
 477
 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.
 482
 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.
 488
 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.
 494
 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.
 505
 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.
 518
 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}.
 525
 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.
 531
 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.
 538
 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.
 545
 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.
 550
 551 @cindex @code{option} directive, TIC54X
 552 @item .option @var{option_list}
 553 Set listing options.  Ignored.
 554
 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}.
 561
 562 @cindex @code{sect} directive, TIC54X
 563 @item .sect "@var{section_name}"
 564 Define a named initialized section and make it the current section.
 565
 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.
 572
 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.
 581
 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.
 587
 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.
 597
 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.
 626
 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.
 632
 633 @cindex @code{tab} directive, TIC54X
 634 @item .tab
 635 Set the tab size in the output listing.  Ignored.
 636
 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.
 651
 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.
 662
 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}.
 667
 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
 683
 684 @node TIC54X-Macros
 685 @section Macros
 686
 687 @cindex TIC54X-specific macros
 688 @cindex macros, TIC54X
 689 Macros do not require explicit dereferencing of arguments (i.e., \ARG).
 690
 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.
 697
 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}.
 709
 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.
 713
 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}.
 718
 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}.
 723
 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.
 728
 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.
 734
 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.
 739
 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.
 743
 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).
 747
 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}.
 751
 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.
 756
 757 @end table
 758
 759 @node TIC54X-MMRegs
 760 @section Memory-mapped Registers
 761
 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:
 766
 767 @table @code
 768 @end table
 769
 770 @node TIC54X-Syntax
 771 @section TIC54X Syntax
 772 @menu
 773 * TIC54X-Chars::                Special Characters
 774 @end menu
 775
 776 @node TIC54X-Chars
 777 @subsection Special Characters
 778
 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.
 783
 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}).
 788
 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.
 791
 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.
 797