include/xtensa-isa.h

   1 /* Interface definition for configurable Xtensa ISA support.
   2    Copyright (C) 2003-2024 Free Software Foundation, Inc.
   3
   4    This file is part of BFD, the Binary File Descriptor library.
   5
   6    This program is free software; you can redistribute it and/or modify
   7    it under the terms of the GNU General Public License as published by
   8    the Free Software Foundation; either version 3 of the License, or
   9    (at your option) any later version.
  10
  11    This program is distributed in the hope that it will be useful,
  12    but WITHOUT ANY WARRANTY; without even the implied warranty of
  13    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  14    GNU General Public License for more details.
  15
  16    You should have received a copy of the GNU General Public License
  17    along with this program; if not, write to the Free Software
  18    Foundation, Inc., 51 Franklin Street - Fifth Floor, Boston, MA 02110-1301,
  19    USA.  */
  20
  21 #ifndef XTENSA_LIBISA_H
  22 #define XTENSA_LIBISA_H
  23
  24 #ifdef __cplusplus
  25 extern "C" {
  26 #endif
  27
  28 /* Version number: This is intended to help support code that works with
  29    versions of this library from multiple Xtensa releases.  */
  30
  31 #define XTENSA_ISA_VERSION 7000
  32
  33 #ifndef uint32
  34 #define uint32 unsigned int
  35 #endif
  36
  37 /* This file defines the interface to the Xtensa ISA library.  This
  38    library contains most of the ISA-specific information for a
  39    particular Xtensa processor.  For example, the set of valid
  40    instructions, their opcode encodings and operand fields are all
  41    included here.
  42
  43    This interface basically defines a number of abstract data types.
  44
  45    . an instruction buffer - for holding the raw instruction bits
  46    . ISA info - information about the ISA as a whole
  47    . instruction formats - instruction size and slot structure
  48    . opcodes - information about individual instructions
  49    . operands - information about register and immediate instruction operands
  50    . stateOperands - information about processor state instruction operands
  51    . interfaceOperands - information about interface instruction operands
  52    . register files - register file information
  53    . processor states - internal processor state information
  54    . system registers - "special registers" and "user registers"
  55    . interfaces - TIE interfaces that are external to the processor
  56    . functional units - TIE shared functions
  57
  58    The interface defines a set of functions to access each data type.
  59    With the exception of the instruction buffer, the internal
  60    representations of the data structures are hidden.  All accesses must
  61    be made through the functions defined here.  */
  62
  63 typedef struct xtensa_isa_opaque { int unused; } *xtensa_isa;
  64
  65
  66 /* Most of the Xtensa ISA entities (e.g., opcodes, regfiles, etc.) are
  67    represented here using sequential integers beginning with 0.  The
  68    specific values are only fixed for a particular instantiation of an
  69    xtensa_isa structure, so these values should only be used
  70    internally.  */
  71
  72 typedef int xtensa_opcode;
  73 typedef int xtensa_format;
  74 typedef int xtensa_regfile;
  75 typedef int xtensa_state;
  76 typedef int xtensa_sysreg;
  77 typedef int xtensa_interface;
  78 typedef int xtensa_funcUnit;
  79
  80
  81 /* Define a unique value for undefined items.  */
  82
  83 #define XTENSA_UNDEFINED -1
  84
  85
  86 /* Overview of using this interface to decode/encode instructions:
  87
  88    Each Xtensa instruction is associated with a particular instruction
  89    format, where the format defines a fixed number of slots for
  90    operations.  The formats for the core Xtensa ISA have only one slot,
  91    but FLIX instructions may have multiple slots.  Within each slot,
  92    there is a single opcode and some number of associated operands.
  93
  94    The encoding and decoding functions operate on instruction buffers,
  95    not on the raw bytes of the instructions.  The same instruction
  96    buffer data structure is used for both entire instructions and
  97    individual slots in those instructions -- the contents of a slot need
  98    to be extracted from or inserted into the buffer for the instruction
  99    as a whole.
 100
 101    Decoding an instruction involves first finding the format, which
 102    identifies the number of slots, and then decoding each slot
 103    separately.  A slot is decoded by finding the opcode and then using
 104    the opcode to determine how many operands there are.  For example:
 105
 106    xtensa_insnbuf_from_chars
 107    xtensa_format_decode
 108    for each slot {
 109      xtensa_format_get_slot
 110      xtensa_opcode_decode
 111      for each operand {
 112        xtensa_operand_get_field
 113        xtensa_operand_decode
 114      }
 115    }
 116
 117    Encoding an instruction is roughly the same procedure in reverse:
 118
 119    xtensa_format_encode
 120    for each slot {
 121      xtensa_opcode_encode
 122      for each operand {
 123        xtensa_operand_encode
 124        xtensa_operand_set_field
 125      }
 126      xtensa_format_set_slot
 127    }
 128    xtensa_insnbuf_to_chars
 129 */
 130
 131 \f
 132 /* Error handling.  */
 133
 134 /* Error codes.  The code for the most recent error condition can be
 135    retrieved with the "errno" function.  For any result other than
 136    xtensa_isa_ok, an error message containing additional information
 137    about the problem can be retrieved using the "error_msg" function.
 138    The error messages are stored in an internal buffer, which should
 139    not be freed and may be overwritten by subsequent operations.  */
 140
 141 typedef enum xtensa_isa_status_enum
 142 {
 143   xtensa_isa_ok = 0,
 144   xtensa_isa_bad_format,
 145   xtensa_isa_bad_slot,
 146   xtensa_isa_bad_opcode,
 147   xtensa_isa_bad_operand,
 148   xtensa_isa_bad_field,
 149   xtensa_isa_bad_iclass,
 150   xtensa_isa_bad_regfile,
 151   xtensa_isa_bad_sysreg,
 152   xtensa_isa_bad_state,
 153   xtensa_isa_bad_interface,
 154   xtensa_isa_bad_funcUnit,
 155   xtensa_isa_wrong_slot,
 156   xtensa_isa_no_field,
 157   xtensa_isa_out_of_memory,
 158   xtensa_isa_buffer_overflow,
 159   xtensa_isa_internal_error,
 160   xtensa_isa_bad_value
 161 } xtensa_isa_status;
 162
 163 extern xtensa_isa_status
 164 xtensa_isa_errno (xtensa_isa isa);
 165
 166 extern char *
 167 xtensa_isa_error_msg (xtensa_isa isa);
 168
 169
 170 \f
 171 /* Instruction buffers.  */
 172
 173 typedef uint32 xtensa_insnbuf_word;
 174 typedef xtensa_insnbuf_word *xtensa_insnbuf;
 175
 176
 177 /* Get the size in "insnbuf_words" of the xtensa_insnbuf array.  */
 178
 179 extern int
 180 xtensa_insnbuf_size (xtensa_isa isa);
 181
 182
 183 /* Allocate an xtensa_insnbuf of the right size.  */
 184
 185 extern xtensa_insnbuf
 186 xtensa_insnbuf_alloc (xtensa_isa isa);
 187
 188
 189 /* Release an xtensa_insnbuf.  */
 190
 191 extern void
 192 xtensa_insnbuf_free (xtensa_isa isa, xtensa_insnbuf buf);
 193
 194
 195 /* Conversion between raw memory (char arrays) and our internal
 196    instruction representation.  This is complicated by the Xtensa ISA's
 197    variable instruction lengths.  When converting to chars, the buffer
 198    must contain a valid instruction so we know how many bytes to copy;
 199    thus, the "to_chars" function returns the number of bytes copied or
 200    XTENSA_UNDEFINED on error.  The "from_chars" function first reads the
 201    minimal number of bytes required to decode the instruction length and
 202    then proceeds to copy the entire instruction into the buffer; if the
 203    memory does not contain a valid instruction, it copies the maximum
 204    number of bytes required for the longest Xtensa instruction.  The
 205    "num_chars" argument may be used to limit the number of bytes that
 206    can be read or written.  Otherwise, if "num_chars" is zero, the
 207    functions may read or write past the end of the code.  */
 208
 209 extern int
 210 xtensa_insnbuf_to_chars (xtensa_isa isa, const xtensa_insnbuf insn,
 211                          unsigned char *cp, int num_chars);
 212
 213 extern void
 214 xtensa_insnbuf_from_chars (xtensa_isa isa, xtensa_insnbuf insn,
 215                            const unsigned char *cp, int num_chars);
 216
 217
 218 \f
 219 /* ISA information.  */
 220
 221 /* Initialize the ISA information.  */
 222
 223 extern xtensa_isa
 224 xtensa_isa_init (xtensa_isa_status *errno_p, char **error_msg_p);
 225
 226
 227 /* Deallocate an xtensa_isa structure.  */
 228
 229 extern void
 230 xtensa_isa_free (xtensa_isa isa);
 231
 232
 233 /* Get the maximum instruction size in bytes.  */
 234
 235 extern int
 236 xtensa_isa_maxlength (xtensa_isa isa);
 237
 238
 239 /* Decode the length in bytes of an instruction in raw memory (not an
 240    insnbuf).  This function reads only the minimal number of bytes
 241    required to decode the instruction length.  Returns
 242    XTENSA_UNDEFINED on error.  */
 243
 244 extern int
 245 xtensa_isa_length_from_chars (xtensa_isa isa, const unsigned char *cp);
 246
 247
 248 /* Get the number of stages in the processor's pipeline.  The pipeline
 249    stage values returned by other functions in this library will range
 250    from 0 to N-1, where N is the value returned by this function.
 251    Note that the stage numbers used here may not correspond to the
 252    actual processor hardware, e.g., the hardware may have additional
 253    stages before stage 0.  Returns XTENSA_UNDEFINED on error.  */
 254
 255 extern int
 256 xtensa_isa_num_pipe_stages (xtensa_isa isa);
 257
 258
 259 /* Get the number of various entities that are defined for this processor.  */
 260
 261 extern int
 262 xtensa_isa_num_formats (xtensa_isa isa);
 263
 264 extern int
 265 xtensa_isa_num_opcodes (xtensa_isa isa);
 266
 267 extern int
 268 xtensa_isa_num_regfiles (xtensa_isa isa);
 269
 270 extern int
 271 xtensa_isa_num_states (xtensa_isa isa);
 272
 273 extern int
 274 xtensa_isa_num_sysregs (xtensa_isa isa);
 275
 276 extern int
 277 xtensa_isa_num_interfaces (xtensa_isa isa);
 278
 279 extern int
 280 xtensa_isa_num_funcUnits (xtensa_isa isa);
 281
 282
 283 \f
 284 /* Instruction formats.  */
 285
 286 /* Get the name of a format.  Returns null on error.  */
 287
 288 extern const char *
 289 xtensa_format_name (xtensa_isa isa, xtensa_format fmt);
 290
 291
 292 /* Given a format name, return the format number.  Returns
 293    XTENSA_UNDEFINED if the name is not a valid format.  */
 294
 295 extern xtensa_format
 296 xtensa_format_lookup (xtensa_isa isa, const char *fmtname);
 297
 298
 299 /* Decode the instruction format from a binary instruction buffer.
 300    Returns XTENSA_UNDEFINED if the format is not recognized.  */
 301
 302 extern xtensa_format
 303 xtensa_format_decode (xtensa_isa isa, const xtensa_insnbuf insn);
 304
 305
 306 /* Set the instruction format field(s) in a binary instruction buffer.
 307    All the other fields are set to zero.  Returns non-zero on error.  */
 308
 309 extern int
 310 xtensa_format_encode (xtensa_isa isa, xtensa_format fmt, xtensa_insnbuf insn);
 311
 312
 313 /* Find the length (in bytes) of an instruction.  Returns
 314    XTENSA_UNDEFINED on error.  */
 315
 316 extern int
 317 xtensa_format_length (xtensa_isa isa, xtensa_format fmt);
 318
 319
 320 /* Get the number of slots in an instruction.  Returns XTENSA_UNDEFINED
 321    on error.  */
 322
 323 extern int
 324 xtensa_format_num_slots (xtensa_isa isa, xtensa_format fmt);
 325
 326
 327 /* Get the opcode for a no-op in a particular slot.
 328    Returns XTENSA_UNDEFINED on error.  */
 329
 330 extern xtensa_opcode
 331 xtensa_format_slot_nop_opcode (xtensa_isa isa, xtensa_format fmt, int slot);
 332
 333
 334 /* Get the bits for a specified slot out of an insnbuf for the
 335    instruction as a whole and put them into an insnbuf for that one
 336    slot, and do the opposite to set a slot.  Return non-zero on error.  */
 337
 338 extern int
 339 xtensa_format_get_slot (xtensa_isa isa, xtensa_format fmt, int slot,
 340                         const xtensa_insnbuf insn, xtensa_insnbuf slotbuf);
 341
 342 extern int
 343 xtensa_format_set_slot (xtensa_isa isa, xtensa_format fmt, int slot,
 344                         xtensa_insnbuf insn, const xtensa_insnbuf slotbuf);
 345
 346
 347 \f
 348 /* Opcode information.  */
 349
 350 /* Translate a mnemonic name to an opcode.  Returns XTENSA_UNDEFINED if
 351    the name is not a valid opcode mnemonic.  */
 352
 353 extern xtensa_opcode
 354 xtensa_opcode_lookup (xtensa_isa isa, const char *opname);
 355
 356
 357 /* Decode the opcode for one instruction slot from a binary instruction
 358    buffer.  Returns the opcode or XTENSA_UNDEFINED if the opcode is
 359    illegal.  */
 360
 361 extern xtensa_opcode
 362 xtensa_opcode_decode (xtensa_isa isa, xtensa_format fmt, int slot,
 363                       const xtensa_insnbuf slotbuf);
 364
 365
 366 /* Set the opcode field(s) for an instruction slot.  All other fields
 367    in the slot are set to zero.  Returns non-zero if the opcode cannot
 368    be encoded.  */
 369
 370 extern int
 371 xtensa_opcode_encode (xtensa_isa isa, xtensa_format fmt, int slot,
 372                       xtensa_insnbuf slotbuf, xtensa_opcode opc);
 373
 374
 375 /* Get the mnemonic name for an opcode.  Returns null on error.  */
 376
 377 extern const char *
 378 xtensa_opcode_name (xtensa_isa isa, xtensa_opcode opc);
 379
 380
 381 /* Check various properties of opcodes.  These functions return 0 if
 382    the condition is false, 1 if the condition is true, and
 383    XTENSA_UNDEFINED on error.  The instructions are classified as
 384    follows:
 385
 386    branch: conditional branch; may fall through to next instruction (B*)
 387    jump: unconditional branch (J, JX, RET*, RF*)
 388    loop: zero-overhead loop (LOOP*)
 389    call: unconditional call; control returns to next instruction (CALL*)
 390
 391    For the opcodes that affect control flow in some way, the branch
 392    target may be specified by an immediate operand or it may be an
 393    address stored in a register.  You can distinguish these by
 394    checking if the instruction has a PC-relative immediate
 395    operand.  */
 396
 397 extern int
 398 xtensa_opcode_is_branch (xtensa_isa isa, xtensa_opcode opc);
 399
 400 extern int
 401 xtensa_opcode_is_jump (xtensa_isa isa, xtensa_opcode opc);
 402
 403 extern int
 404 xtensa_opcode_is_loop (xtensa_isa isa, xtensa_opcode opc);
 405
 406 extern int
 407 xtensa_opcode_is_call (xtensa_isa isa, xtensa_opcode opc);
 408
 409
 410 /* Find the number of ordinary operands, state operands, and interface
 411    operands for an instruction.  These return XTENSA_UNDEFINED on
 412    error.  */
 413
 414 extern int
 415 xtensa_opcode_num_operands (xtensa_isa isa, xtensa_opcode opc);
 416
 417 extern int
 418 xtensa_opcode_num_stateOperands (xtensa_isa isa, xtensa_opcode opc);
 419
 420 extern int
 421 xtensa_opcode_num_interfaceOperands (xtensa_isa isa, xtensa_opcode opc);
 422
 423
 424 /* Get functional unit usage requirements for an opcode.  Each "use"
 425    is identified by a <functional unit, pipeline stage> pair.  The
 426    "num_funcUnit_uses" function returns the number of these "uses" or
 427    XTENSA_UNDEFINED on error.  The "funcUnit_use" function returns
 428    a pointer to a "use" pair or null on error.  */
 429
 430 typedef struct xtensa_funcUnit_use_struct
 431 {
 432   xtensa_funcUnit unit;
 433   int stage;
 434 } xtensa_funcUnit_use;
 435
 436 extern int
 437 xtensa_opcode_num_funcUnit_uses (xtensa_isa isa, xtensa_opcode opc);
 438
 439 extern xtensa_funcUnit_use *
 440 xtensa_opcode_funcUnit_use (xtensa_isa isa, xtensa_opcode opc, int u);
 441
 442
 443 \f
 444 /* Operand information.  */
 445
 446 /* Get the name of an operand.  Returns null on error.  */
 447
 448 extern const char *
 449 xtensa_operand_name (xtensa_isa isa, xtensa_opcode opc, int opnd);
 450
 451
 452 /* Some operands are "invisible", i.e., not explicitly specified in
 453    assembly language.  When assembling an instruction, you need not set
 454    the values of invisible operands, since they are either hardwired or
 455    derived from other field values.  The values of invisible operands
 456    can be examined in the same way as other operands, but remember that
 457    an invisible operand may get its value from another visible one, so
 458    the entire instruction must be available before examining the
 459    invisible operand values.  This function returns 1 if an operand is
 460    visible, 0 if it is invisible, or XTENSA_UNDEFINED on error.  Note
 461    that whether an operand is visible is orthogonal to whether it is
 462    "implicit", i.e., whether it is encoded in a field in the
 463    instruction.  */
 464
 465 extern int
 466 xtensa_operand_is_visible (xtensa_isa isa, xtensa_opcode opc, int opnd);
 467
 468
 469 /* Check if an operand is an input ('i'), output ('o'), or inout ('m')
 470    operand.  Note: The output operand of a conditional assignment
 471    (e.g., movnez) appears here as an inout ('m') even if it is declared
 472    in the TIE code as an output ('o'); this allows the compiler to
 473    properly handle register allocation for conditional assignments.
 474    Returns 0 on error.  */
 475
 476 extern char
 477 xtensa_operand_inout (xtensa_isa isa, xtensa_opcode opc, int opnd);
 478
 479
 480 /* Get and set the raw (encoded) value of the field for the specified
 481    operand.  The "set" function does not check if the value fits in the
 482    field; that is done by the "encode" function below.  Both of these
 483    functions return non-zero on error, e.g., if the field is not defined
 484    for the specified slot.  */
 485
 486 extern int
 487 xtensa_operand_get_field (xtensa_isa isa, xtensa_opcode opc, int opnd,
 488                           xtensa_format fmt, int slot,
 489                           const xtensa_insnbuf slotbuf, uint32 *valp);
 490
 491 extern int
 492 xtensa_operand_set_field (xtensa_isa isa, xtensa_opcode opc, int opnd,
 493                           xtensa_format fmt, int slot,
 494                           xtensa_insnbuf slotbuf, uint32 val);
 495
 496
 497 /* Encode and decode operands.  The raw bits in the operand field may
 498    be encoded in a variety of different ways.  These functions hide
 499    the details of that encoding.  The result values are returned through
 500    the argument pointer.  The return value is non-zero on error.  */
 501
 502 extern int
 503 xtensa_operand_encode (xtensa_isa isa, xtensa_opcode opc, int opnd,
 504                        uint32 *valp);
 505
 506 extern int
 507 xtensa_operand_decode (xtensa_isa isa, xtensa_opcode opc, int opnd,
 508                        uint32 *valp);
 509
 510
 511 /* An operand may be either a register operand or an immediate of some
 512    sort (e.g., PC-relative or not).  The "is_register" function returns
 513    0 if the operand is an immediate, 1 if it is a register, and
 514    XTENSA_UNDEFINED on error.  The "regfile" function returns the
 515    regfile for a register operand, or XTENSA_UNDEFINED on error.  */
 516
 517 extern int
 518 xtensa_operand_is_register (xtensa_isa isa, xtensa_opcode opc, int opnd);
 519
 520 extern xtensa_regfile
 521 xtensa_operand_regfile (xtensa_isa isa, xtensa_opcode opc, int opnd);
 522
 523
 524 /* Register operands may span multiple consecutive registers, e.g., a
 525    64-bit data type may occupy two 32-bit registers.  Only the first
 526    register is encoded in the operand field.  This function specifies
 527    the number of consecutive registers occupied by this operand.  For
 528    non-register operands, the return value is undefined.  Returns
 529    XTENSA_UNDEFINED on error.  */
 530
 531 extern int
 532 xtensa_operand_num_regs (xtensa_isa isa, xtensa_opcode opc, int opnd);
 533
 534
 535 /* Some register operands do not completely identify the register being
 536    accessed.  For example, the operand value may be added to an internal
 537    state value.  By definition, this implies that the corresponding
 538    regfile is not allocatable.  Unknown registers should generally be
 539    treated with worst-case assumptions.  The function returns 0 if the
 540    register value is unknown, 1 if known, and XTENSA_UNDEFINED on
 541    error.  */
 542
 543 extern int
 544 xtensa_operand_is_known_reg (xtensa_isa isa, xtensa_opcode opc, int opnd);
 545
 546
 547 /* Check if an immediate operand is PC-relative.  Returns 0 for register
 548    operands and non-PC-relative immediates, 1 for PC-relative
 549    immediates, and XTENSA_UNDEFINED on error.  */
 550
 551 extern int
 552 xtensa_operand_is_PCrelative (xtensa_isa isa, xtensa_opcode opc, int opnd);
 553
 554
 555 /* For PC-relative offset operands, the interpretation of the offset may
 556    vary between opcodes, e.g., is it relative to the current PC or that
 557    of the next instruction?  The following functions are defined to
 558    perform PC-relative relocations and to undo them (as in the
 559    disassembler).  The "do_reloc" function takes the desired address
 560    value and the PC of the current instruction and sets the value to the
 561    corresponding PC-relative offset (which can then be encoded and
 562    stored into the operand field).  The "undo_reloc" function takes the
 563    unencoded offset value and the current PC and sets the value to the
 564    appropriate address.  The return values are non-zero on error.  Note
 565    that these functions do not replace the encode/decode functions; the
 566    operands must be encoded/decoded separately and the encode functions
 567    are responsible for detecting invalid operand values.  */
 568
 569 extern int
 570 xtensa_operand_do_reloc (xtensa_isa isa, xtensa_opcode opc, int opnd,
 571                          uint32 *valp, uint32 pc);
 572
 573 extern int
 574 xtensa_operand_undo_reloc (xtensa_isa isa, xtensa_opcode opc, int opnd,
 575                            uint32 *valp, uint32 pc);
 576
 577
 578 \f
 579 /* State Operands.  */
 580
 581 /* Get the state accessed by a state operand.  Returns XTENSA_UNDEFINED
 582    on error.  */
 583
 584 extern xtensa_state
 585 xtensa_stateOperand_state (xtensa_isa isa, xtensa_opcode opc, int stOp);
 586
 587
 588 /* Check if a state operand is an input ('i'), output ('o'), or inout
 589    ('m') operand.  Returns 0 on error.  */
 590
 591 extern char
 592 xtensa_stateOperand_inout (xtensa_isa isa, xtensa_opcode opc, int stOp);
 593
 594
 595 \f
 596 /* Interface Operands.  */
 597
 598 /* Get the external interface accessed by an interface operand.
 599    Returns XTENSA_UNDEFINED on error.  */
 600
 601 extern xtensa_interface
 602 xtensa_interfaceOperand_interface (xtensa_isa isa, xtensa_opcode opc,
 603                                    int ifOp);
 604
 605
 606 \f
 607 /* Register Files.  */
 608
 609 /* Regfiles include both "real" regfiles and "views", where a view
 610    allows a group of adjacent registers in a real "parent" regfile to be
 611    viewed as a single register.  A regfile view has all the same
 612    properties as its parent except for its (long) name, bit width, number
 613    of entries, and default ctype.  You can use the parent function to
 614    distinguish these two classes.  */
 615
 616 /* Look up a regfile by either its name or its abbreviated "short name".
 617    Returns XTENSA_UNDEFINED on error.  The "lookup_shortname" function
 618    ignores "view" regfiles since they always have the same shortname as
 619    their parents.  */
 620
 621 extern xtensa_regfile
 622 xtensa_regfile_lookup (xtensa_isa isa, const char *name);
 623
 624 extern xtensa_regfile
 625 xtensa_regfile_lookup_shortname (xtensa_isa isa, const char *shortname);
 626
 627
 628 /* Get the name or abbreviated "short name" of a regfile.
 629    Returns null on error.  */
 630
 631 extern const char *
 632 xtensa_regfile_name (xtensa_isa isa, xtensa_regfile rf);
 633
 634 extern const char *
 635 xtensa_regfile_shortname (xtensa_isa isa, xtensa_regfile rf);
 636
 637
 638 /* Get the parent regfile of a "view" regfile.  If the regfile is not a
 639    view, the result is the same as the input parameter.  Returns
 640    XTENSA_UNDEFINED on error.  */
 641
 642 extern xtensa_regfile
 643 xtensa_regfile_view_parent (xtensa_isa isa, xtensa_regfile rf);
 644
 645
 646 /* Get the bit width of a regfile or regfile view.
 647    Returns XTENSA_UNDEFINED on error.  */
 648
 649 extern int
 650 xtensa_regfile_num_bits (xtensa_isa isa, xtensa_regfile rf);
 651
 652
 653 /* Get the number of regfile entries.  Returns XTENSA_UNDEFINED on
 654    error.  */
 655
 656 extern int
 657 xtensa_regfile_num_entries (xtensa_isa isa, xtensa_regfile rf);
 658
 659
 660 \f
 661 /* Processor States.  */
 662
 663 /* Look up a state by name.  Returns XTENSA_UNDEFINED on error.  */
 664
 665 extern xtensa_state
 666 xtensa_state_lookup (xtensa_isa isa, const char *name);
 667
 668
 669 /* Get the name for a processor state.  Returns null on error.  */
 670
 671 extern const char *
 672 xtensa_state_name (xtensa_isa isa, xtensa_state st);
 673
 674
 675 /* Get the bit width for a processor state.
 676    Returns XTENSA_UNDEFINED on error.  */
 677
 678 extern int
 679 xtensa_state_num_bits (xtensa_isa isa, xtensa_state st);
 680
 681
 682 /* Check if a state is exported from the processor core.  Returns 0 if
 683    the condition is false, 1 if the condition is true, and
 684    XTENSA_UNDEFINED on error.  */
 685
 686 extern int
 687 xtensa_state_is_exported (xtensa_isa isa, xtensa_state st);
 688
 689
 690 /* Check for a "shared_or" state.  Returns 0 if the condition is false,
 691    1 if the condition is true, and XTENSA_UNDEFINED on error.  */
 692
 693 extern int
 694 xtensa_state_is_shared_or (xtensa_isa isa, xtensa_state st);
 695
 696
 697 \f
 698 /* Sysregs ("special registers" and "user registers").  */
 699
 700 /* Look up a register by its number and whether it is a "user register"
 701    or a "special register".  Returns XTENSA_UNDEFINED if the sysreg does
 702    not exist.  */
 703
 704 extern xtensa_sysreg
 705 xtensa_sysreg_lookup (xtensa_isa isa, int num, int is_user);
 706
 707
 708 /* Check if there exists a sysreg with a given name.
 709    If not, this function returns XTENSA_UNDEFINED.  */
 710
 711 extern xtensa_sysreg
 712 xtensa_sysreg_lookup_name (xtensa_isa isa, const char *name);
 713
 714
 715 /* Get the name of a sysreg.  Returns null on error.  */
 716
 717 extern const char *
 718 xtensa_sysreg_name (xtensa_isa isa, xtensa_sysreg sysreg);
 719
 720
 721 /* Get the register number.  Returns XTENSA_UNDEFINED on error.  */
 722
 723 extern int
 724 xtensa_sysreg_number (xtensa_isa isa, xtensa_sysreg sysreg);
 725
 726
 727 /* Check if a sysreg is a "special register" or a "user register".
 728    Returns 0 for special registers, 1 for user registers and
 729    XTENSA_UNDEFINED on error.  */
 730
 731 extern int
 732 xtensa_sysreg_is_user (xtensa_isa isa, xtensa_sysreg sysreg);
 733
 734
 735 \f
 736 /* Interfaces.  */
 737
 738 /* Find an interface by name.  The return value is XTENSA_UNDEFINED if
 739    the specified interface is not found.  */
 740
 741 extern xtensa_interface
 742 xtensa_interface_lookup (xtensa_isa isa, const char *ifname);
 743
 744
 745 /* Get the name of an interface.  Returns null on error.  */
 746
 747 extern const char *
 748 xtensa_interface_name (xtensa_isa isa, xtensa_interface intf);
 749
 750
 751 /* Get the bit width for an interface.
 752    Returns XTENSA_UNDEFINED on error.  */
 753
 754 extern int
 755 xtensa_interface_num_bits (xtensa_isa isa, xtensa_interface intf);
 756
 757
 758 /* Check if an interface is an input ('i') or output ('o') with respect
 759    to the Xtensa processor core.  Returns 0 on error.  */
 760
 761 extern char
 762 xtensa_interface_inout (xtensa_isa isa, xtensa_interface intf);
 763
 764
 765 /* Check if accessing an interface has potential side effects.
 766    Currently "data" interfaces have side effects and "control"
 767    interfaces do not.  Returns 1 if there are side effects, 0 if not,
 768    and XTENSA_UNDEFINED on error.  */
 769
 770 extern int
 771 xtensa_interface_has_side_effect (xtensa_isa isa, xtensa_interface intf);
 772
 773
 774 /* Some interfaces may be related such that accessing one interface
 775    has side effects on a set of related interfaces.  The interfaces
 776    are partitioned into equivalence classes of related interfaces, and
 777    each class is assigned a unique identifier number.  This function
 778    returns the class identifier for an interface, or XTENSA_UNDEFINED
 779    on error.  These identifiers can be compared to determine if two
 780    interfaces are related; the specific values of the identifiers have
 781    no particular meaning otherwise.  */
 782
 783 extern int
 784 xtensa_interface_class_id (xtensa_isa isa, xtensa_interface intf);
 785
 786
 787 \f
 788 /* Functional Units.  */
 789
 790 /* Find a functional unit by name.  The return value is XTENSA_UNDEFINED if
 791    the specified unit is not found.  */
 792
 793 extern xtensa_funcUnit
 794 xtensa_funcUnit_lookup (xtensa_isa isa, const char *fname);
 795
 796
 797 /* Get the name of a functional unit.  Returns null on error.  */
 798
 799 extern const char *
 800 xtensa_funcUnit_name (xtensa_isa isa, xtensa_funcUnit fun);
 801
 802
 803 /* Functional units may be replicated.  See how many instances of a
 804    particular function unit exist.  Returns XTENSA_UNDEFINED on error.  */
 805
 806 extern int
 807 xtensa_funcUnit_num_copies (xtensa_isa isa, xtensa_funcUnit fun);
 808
 809
 810 #ifdef __cplusplus
 811 }
 812 #endif
 813 #endif /* XTENSA_LIBISA_H */