gas/doc/c-tilegx.texi

   1 @c Copyright (C) 2011-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 man end
   5
   6 @ifset GENERIC
   7 @page
   8 @node TILE-Gx-Dependent
   9 @chapter TILE-Gx Dependent Features
  10 @end ifset
  11 @ifclear GENERIC
  12 @node Machine Dependencies
  13 @chapter TILE-Gx Dependent Features
  14 @end ifclear
  15
  16 @cindex TILE-Gx support
  17 @menu
  18 * TILE-Gx Options::             TILE-Gx Options
  19 * TILE-Gx Syntax::              TILE-Gx Syntax
  20 * TILE-Gx Directives::          TILE-Gx Directives
  21 @end menu
  22
  23 @node TILE-Gx Options
  24 @section Options
  25
  26 The following table lists all available TILE-Gx specific options:
  27
  28 @c man begin OPTIONS
  29 @table @gcctabopt
  30 @cindex @samp{-m32} option, TILE-Gx
  31 @cindex @samp{-m64} option, TILE-Gx
  32 @item -m32 | -m64
  33 Select the word size, either 32 bits or 64 bits.
  34
  35 @cindex @samp{-EB} option, TILE-Gx
  36 @cindex @samp{-EL} option, TILE-Gx
  37 @item -EB | -EL
  38 Select the endianness, either big-endian (-EB) or little-endian (-EL).
  39
  40 @end table
  41 @c man end
  42
  43 @node TILE-Gx Syntax
  44 @section Syntax
  45 @cindex TILE-Gx syntax
  46 @cindex syntax, TILE-Gx
  47
  48 Block comments are delimited by @samp{/*} and @samp{*/}.  End of line
  49 comments may be introduced by @samp{#}.
  50
  51 Instructions consist of a leading opcode or macro name followed by
  52 whitespace and an optional comma-separated list of operands:
  53
  54 @smallexample
  55 @var{opcode} [@var{operand}, @dots{}]
  56 @end smallexample
  57
  58 Instructions must be separated by a newline or semicolon.
  59
  60 There are two ways to write code: either write naked instructions,
  61 which the assembler is free to combine into VLIW bundles, or specify
  62 the VLIW bundles explicitly.
  63
  64 Bundles are specified using curly braces:
  65
  66 @smallexample
  67 @{ @var{add} r3,r4,r5 ; @var{add} r7,r8,r9 ; @var{lw} r10,r11 @}
  68 @end smallexample
  69
  70 A bundle can span multiple lines. If you want to put multiple
  71 instructions on a line, whether in a bundle or not, you need to
  72 separate them with semicolons as in this example.
  73
  74 A bundle may contain one or more instructions, up to the limit
  75 specified by the ISA (currently three). If fewer instructions are
  76 specified than the hardware supports in a bundle, the assembler
  77 inserts @code{fnop} instructions automatically.
  78
  79 The assembler will prefer to preserve the ordering of instructions
  80 within the bundle, putting the first instruction in a lower-numbered
  81 pipeline than the next one, etc.  This fact, combined with the
  82 optional use of explicit @code{fnop} or @code{nop} instructions,
  83 allows precise control over which pipeline executes each instruction.
  84
  85 If the instructions cannot be bundled in the listed order, the
  86 assembler will automatically try to find a valid pipeline
  87 assignment. If there is no way to bundle the instructions together,
  88 the assembler reports an error.
  89
  90 The assembler does not yet auto-bundle (automatically combine multiple
  91 instructions into one bundle), but it reserves the right to do so in
  92 the future.  If you want to force an instruction to run by itself, put
  93 it in a bundle explicitly with curly braces and use @code{nop}
  94 instructions (not @code{fnop}) to fill the remaining pipeline slots in
  95 that bundle.
  96
  97 @menu
  98 * TILE-Gx Opcodes::              Opcode Naming Conventions.
  99 * TILE-Gx Registers::            Register Naming.
 100 * TILE-Gx Modifiers::            Symbolic Operand Modifiers.
 101 @end menu
 102
 103 @node TILE-Gx Opcodes
 104 @subsection Opcode Names
 105 @cindex TILE-Gx opcode names
 106 @cindex opcode names, TILE-Gx
 107
 108 For a complete list of opcodes and descriptions of their semantics,
 109 see @cite{TILE-Gx Instruction Set Architecture}, available upon
 110 request at www.tilera.com.
 111
 112 @node TILE-Gx Registers
 113 @subsection Register Names
 114 @cindex TILE-Gx register names
 115 @cindex register names, TILE-Gx
 116
 117 General-purpose registers are represented by predefined symbols of the
 118 form @samp{r@var{N}}, where @var{N} represents a number between
 119 @code{0} and @code{63}.  However, the following registers have
 120 canonical names that must be used instead:
 121
 122 @table @code
 123 @item r54
 124 sp
 125
 126 @item r55
 127 lr
 128
 129 @item r56
 130 sn
 131
 132 @item r57
 133 idn0
 134
 135 @item r58
 136 idn1
 137
 138 @item r59
 139 udn0
 140
 141 @item r60
 142 udn1
 143
 144 @item r61
 145 udn2
 146
 147 @item r62
 148 udn3
 149
 150 @item r63
 151 zero
 152
 153 @end table
 154
 155 The assembler will emit a warning if a numeric name is used instead of
 156 the non-numeric name.  The @code{.no_require_canonical_reg_names}
 157 assembler pseudo-op turns off this
 158 warning. @code{.require_canonical_reg_names} turns it back on.
 159
 160 @node TILE-Gx Modifiers
 161 @subsection Symbolic Operand Modifiers
 162 @cindex TILE-Gx modifiers
 163 @cindex symbol modifiers, TILE-Gx
 164
 165 The assembler supports several modifiers when using symbol addresses
 166 in TILE-Gx instruction operands.  The general syntax is the following:
 167
 168 @smallexample
 169 modifier(symbol)
 170 @end smallexample
 171
 172 The following modifiers are supported:
 173
 174 @table @code
 175
 176 @item hw0
 177
 178 This modifier is used to load bits 0-15 of the symbol's address.
 179
 180 @item hw1
 181
 182 This modifier is used to load bits 16-31 of the symbol's address.
 183
 184 @item hw2
 185
 186 This modifier is used to load bits 32-47 of the symbol's address.
 187
 188 @item hw3
 189
 190 This modifier is used to load bits 48-63 of the symbol's address.
 191
 192 @item hw0_last
 193
 194 This modifier yields the same value as @code{hw0}, but it also checks
 195 that the value does not overflow.
 196
 197 @item hw1_last
 198
 199 This modifier yields the same value as @code{hw1}, but it also checks
 200 that the value does not overflow.
 201
 202 @item hw2_last
 203
 204 This modifier yields the same value as @code{hw2}, but it also checks
 205 that the value does not overflow.
 206
 207 A 48-bit symbolic value is constructed by using the following idiom:
 208
 209 @smallexample
 210 moveli r0, hw2_last(sym)
 211 shl16insli r0, r0, hw1(sym)
 212 shl16insli r0, r0, hw0(sym)
 213 @end smallexample
 214
 215 @item hw0_got
 216
 217 This modifier is used to load bits 0-15 of the symbol's offset in the
 218 GOT entry corresponding to the symbol.
 219
 220 @item hw0_last_got
 221
 222 This modifier yields the same value as @code{hw0_got}, but it also
 223 checks that the value does not overflow.
 224
 225 @item hw1_last_got
 226
 227 This modifier is used to load bits 16-31 of the symbol's offset in the
 228 GOT entry corresponding to the symbol, and it also checks that the
 229 value does not overflow.
 230
 231 @item plt
 232
 233 This modifier is used for function symbols.  It causes a
 234 @emph{procedure linkage table}, an array of code stubs, to be created
 235 at the time the shared object is created or linked against, together
 236 with a global offset table entry.  The value is a pc-relative offset
 237 to the corresponding stub code in the procedure linkage table.  This
 238 arrangement causes the run-time symbol resolver to be called to look
 239 up and set the value of the symbol the first time the function is
 240 called (at latest; depending environment variables).  It is only safe
 241 to leave the symbol unresolved this way if all references are function
 242 calls.
 243
 244 @item hw0_plt
 245
 246 This modifier is used to load bits 0-15 of the pc-relative address of
 247 a plt entry.
 248
 249 @item hw1_plt
 250
 251 This modifier is used to load bits 16-31 of the pc-relative address of
 252 a plt entry.
 253
 254 @item hw1_last_plt
 255
 256 This modifier yields the same value as @code{hw1_plt}, but it also
 257 checks that the value does not overflow.
 258
 259 @item hw2_last_plt
 260
 261 This modifier is used to load bits 32-47 of the pc-relative address of
 262 a plt entry, and it also checks that the value does not overflow.
 263
 264 @item hw0_tls_gd
 265
 266 This modifier is used to load bits 0-15 of the offset of the GOT entry
 267 of the symbol's TLS descriptor, to be used for general-dynamic TLS
 268 accesses.
 269
 270 @item hw0_last_tls_gd
 271
 272 This modifier yields the same value as @code{hw0_tls_gd}, but it also
 273 checks that the value does not overflow.
 274
 275 @item hw1_last_tls_gd
 276
 277 This modifier is used to load bits 16-31 of the offset of the GOT
 278 entry of the symbol's TLS descriptor, to be used for general-dynamic
 279 TLS accesses.  It also checks that the value does not overflow.
 280
 281 @item hw0_tls_ie
 282
 283 This modifier is used to load bits 0-15 of the offset of the GOT entry
 284 containing the offset of the symbol's address from the TCB, to be used
 285 for initial-exec TLS accesses.
 286
 287 @item hw0_last_tls_ie
 288
 289 This modifier yields the same value as @code{hw0_tls_ie}, but it also
 290 checks that the value does not overflow.
 291
 292 @item hw1_last_tls_ie
 293
 294 This modifier is used to load bits 16-31 of the offset of the GOT
 295 entry containing the offset of the symbol's address from the TCB, to
 296 be used for initial-exec TLS accesses.  It also checks that the value
 297 does not overflow.
 298
 299 @item hw0_tls_le
 300
 301 This modifier is used to load bits 0-15 of the offset of the symbol's
 302 address from the TCB, to be used for local-exec TLS accesses.
 303
 304 @item hw0_last_tls_le
 305
 306 This modifier yields the same value as @code{hw0_tls_le}, but it also
 307 checks that the value does not overflow.
 308
 309 @item hw1_last_tls_le
 310
 311 This modifier is used to load bits 16-31 of the offset of the symbol's
 312 address from the TCB, to be used for local-exec TLS accesses.  It
 313 also checks that the value does not overflow.
 314
 315 @item tls_gd_call
 316
 317 This modifier is used to tag an instruction as the ``call'' part of a
 318 calling sequence for a TLS GD reference of its operand.
 319
 320 @item tls_gd_add
 321
 322 This modifier is used to tag an instruction as the ``add'' part of a
 323 calling sequence for a TLS GD reference of its operand.
 324
 325 @item tls_ie_load
 326
 327 This modifier is used to tag an instruction as the ``load'' part of a
 328 calling sequence for a TLS IE reference of its operand.
 329
 330 @end table
 331
 332 @node TILE-Gx Directives
 333 @section TILE-Gx Directives
 334 @cindex machine directives, TILE-Gx
 335 @cindex TILE-Gx machine directives
 336
 337 @table @code
 338
 339 @cindex @code{.align} directive, TILE-Gx
 340 @item .align @var{expression} [, @var{expression}]
 341 This is the generic @var{.align} directive.  The first argument is the
 342 requested alignment in bytes.
 343
 344 @cindex @code{.allow_suspicious_bundles} directive, TILE-Gx
 345 @item .allow_suspicious_bundles
 346 Turns on error checking for combinations of instructions in a bundle
 347 that probably indicate a programming error.  This is on by default.
 348
 349 @item .no_allow_suspicious_bundles
 350 Turns off error checking for combinations of instructions in a bundle
 351 that probably indicate a programming error.
 352
 353 @cindex @code{.require_canonical_reg_names} directive, TILE-Gx
 354 @item .require_canonical_reg_names
 355 Require that canonical register names be used, and emit a warning if
 356 the numeric names are used.  This is on by default.
 357
 358 @item .no_require_canonical_reg_names
 359 Permit the use of numeric names for registers that have canonical
 360 names.
 361
 362 @end table