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