include/xtensa-isa.h

   1 /* Interface definition for configurable Xtensa ISA support.
   2    Copyright 2003 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 2 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., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.  */
  19
  20 #ifndef XTENSA_LIBISA_H
  21 #define XTENSA_LIBISA_H
  22
  23 /* Use the statically-linked version for the GNU tools.  */
  24 #define STATIC_LIBISA 1
  25
  26 #ifdef __cplusplus
  27 extern "C" {
  28 #endif
  29
  30 #ifndef uint32
  31 #define uint32 unsigned int
  32 #endif
  33
  34 /* This file defines the interface to the Xtensa ISA library.  This library
  35    contains most of the ISA-specific information for a particular Xtensa
  36    processor.  For example, the set of valid instructions, their opcode
  37    encodings and operand fields are all included here.  To support Xtensa's
  38    configurability and user-defined instruction extensions (i.e., TIE), the
  39    library is initialized by loading one or more dynamic libraries; only a
  40    small set of interface code is present in the statically-linked portion
  41    of the library.
  42
  43    This interface basically defines four 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    . opcode info - information about individual instructions
  48    . operand info - information about specific instruction operands
  49
  50    It would be nice to implement these as classes in C++, but the library is
  51    implemented in C to match the expectations of the GNU tools.
  52    Instead, the interface defines a set of functions to access each data
  53    type.  With the exception of the instruction buffer, the internal
  54    representations of the data structures are hidden.  All accesses must be
  55    made through the functions defined here.  */
  56
  57 typedef void* xtensa_isa;
  58 typedef void* xtensa_operand;
  59
  60
  61 /* Opcodes are represented here using sequential integers beginning with 0.
  62    The specific value used for a particular opcode is only fixed for a
  63    particular instantiation of an xtensa_isa structure, so these values
  64    should only be used internally.  */
  65 typedef int xtensa_opcode;
  66
  67 /* Define a unique value for undefined opcodes ("static const int" doesn't
  68    seem to work for this because EGCS 1.0.3 on i686-Linux without -O won't
  69    allow it to be used as an initializer).  */
  70 #define XTENSA_UNDEFINED -1
  71
  72
  73 typedef int libisa_module_specifier;
  74
  75 extern xtensa_isa xtensa_isa_init (void);
  76
  77
  78 /* Instruction buffers.  */
  79
  80 typedef uint32 xtensa_insnbuf_word;
  81 typedef xtensa_insnbuf_word *xtensa_insnbuf;
  82
  83 /* Get the size in words of the xtensa_insnbuf array.  */
  84 extern int xtensa_insnbuf_size (xtensa_isa);
  85
  86 /* Allocate (with malloc) an xtensa_insnbuf of the right size.  */
  87 extern xtensa_insnbuf xtensa_insnbuf_alloc (xtensa_isa);
  88
  89 /* Release (with free) an xtensa_insnbuf of the right size.  */
  90 extern void xtensa_insnbuf_free (xtensa_insnbuf);
  91
  92 /* Inward and outward conversion from memory images (byte streams) to our
  93    internal instruction representation.  */
  94 extern void xtensa_insnbuf_to_chars (xtensa_isa, const xtensa_insnbuf,
  95                                      char *);
  96
  97 extern void xtensa_insnbuf_from_chars (xtensa_isa, xtensa_insnbuf,
  98                                        const char *);
  99
 100
 101 /* ISA information.  */
 102
 103 /* Load the ISA information from a shared library.  If successful, this returns
 104    a value which identifies the ISA for use in subsequent calls to the ISA
 105    library; otherwise, it returns NULL.  Multiple ISAs can be loaded to support
 106    heterogeneous multiprocessor systems.  */
 107 extern xtensa_isa xtensa_load_isa (libisa_module_specifier);
 108
 109 /* Extend an existing set of ISA information by loading an additional shared
 110    library of ISA information.  This is primarily intended for loading TIE
 111    extensions.  If successful, the return value is non-zero.  */
 112 extern int xtensa_extend_isa (xtensa_isa, libisa_module_specifier);
 113
 114 /* The default ISA.  This variable is set automatically to the ISA most
 115    recently loaded and is provided as a convenience.  An exception is the GNU
 116    opcodes library, where there is a fixed interface that does not allow
 117    passing the ISA as a parameter and the ISA must be taken from this global
 118    variable.  (Note: Since this variable is just a convenience, it is not
 119    exported when libisa is built as a DLL, due to the hassle of dealing with
 120    declspecs.)  */
 121 extern xtensa_isa xtensa_default_isa;
 122
 123
 124 /* Deallocate an xtensa_isa structure.  */
 125 extern void xtensa_isa_free (xtensa_isa);
 126
 127 /* Get the maximum instruction size in bytes.  */
 128 extern int xtensa_insn_maxlength (xtensa_isa);
 129
 130 /* Get the total number of opcodes for this processor.  */
 131 extern int xtensa_num_opcodes (xtensa_isa);
 132
 133 /* Translate a mnemonic name to an opcode.  Returns XTENSA_UNDEFINED if
 134    the name is not a valid opcode mnemonic.  */
 135 extern xtensa_opcode xtensa_opcode_lookup (xtensa_isa, const char *);
 136
 137 /* Decode a binary instruction buffer.  Returns the opcode or
 138    XTENSA_UNDEFINED if the instruction is illegal.  */
 139 extern xtensa_opcode xtensa_decode_insn (xtensa_isa, const xtensa_insnbuf);
 140
 141
 142 /* Opcode information.  */
 143
 144 /* Set the opcode field(s) in a binary instruction buffer.  The operand
 145    fields are set to zero.  */
 146 extern void xtensa_encode_insn (xtensa_isa, xtensa_opcode, xtensa_insnbuf);
 147
 148 /* Get the mnemonic name for an opcode.  */
 149 extern const char * xtensa_opcode_name (xtensa_isa, xtensa_opcode);
 150
 151 /* Find the length (in bytes) of an instruction.  */
 152 extern int xtensa_insn_length (xtensa_isa, xtensa_opcode);
 153
 154 /* Find the length of an instruction by looking only at the first byte.  */
 155 extern int xtensa_insn_length_from_first_byte (xtensa_isa, char);
 156
 157 /* Find the number of operands for an instruction.  */
 158 extern int xtensa_num_operands (xtensa_isa, xtensa_opcode);
 159
 160 /* Get the information about operand number "opnd" of a particular opcode.  */
 161 extern xtensa_operand xtensa_get_operand (xtensa_isa, xtensa_opcode, int);
 162
 163 /* Operand information.  */
 164
 165 /* Find the kind of operand.  There are three possibilities:
 166    1) PC-relative immediates (e.g., "l", "L").  These can be identified with
 167       the xtensa_operand_isPCRelative function.
 168    2) non-PC-relative immediates ("i").
 169    3) register-file short names (e.g., "a", "b", "m" and others defined
 170       via TIE).  */
 171 extern char * xtensa_operand_kind (xtensa_operand);
 172
 173 /* Check if an operand is an input ('<'), output ('>'), or inout ('=')
 174    operand.  Note: The output operand of a conditional assignment
 175    (e.g., movnez) appears here as an inout ('=') even if it is declared
 176    in the TIE code as an output ('>'); this allows the compiler to
 177    properly handle register allocation for conditional assignments.  */
 178 extern char xtensa_operand_inout (xtensa_operand);
 179
 180 /* Get and set the raw (encoded) value of the field for the specified
 181    operand.  The "set" function does not check if the value fits in the
 182    field; that is done by the "encode" function below.  */
 183 extern uint32 xtensa_operand_get_field (xtensa_operand, const xtensa_insnbuf);
 184
 185 extern void xtensa_operand_set_field (xtensa_operand, xtensa_insnbuf, uint32);
 186
 187
 188 /* Encode and decode operands.  The raw bits in the operand field
 189    may be encoded in a variety of different ways.  These functions hide the
 190    details of that encoding.  The encode function has a special return type
 191    (xtensa_encode_result) to indicate success or the reason for failure; the
 192    encoded value is returned through the argument pointer.  The decode function
 193    has no possibility of failure and returns the decoded value.  */
 194
 195 typedef enum
 196 {
 197   xtensa_encode_result_ok,
 198   xtensa_encode_result_align,
 199   xtensa_encode_result_not_in_table,
 200   xtensa_encode_result_too_low,
 201   xtensa_encode_result_too_high,
 202   xtensa_encode_result_not_ok,
 203   xtensa_encode_result_max = xtensa_encode_result_not_ok
 204 } xtensa_encode_result;
 205
 206 extern xtensa_encode_result xtensa_operand_encode (xtensa_operand, uint32 *);
 207
 208 extern uint32 xtensa_operand_decode (xtensa_operand, uint32);
 209
 210
 211 /* For PC-relative offset operands, the interpretation of the offset may vary
 212    between opcodes, e.g., is it relative to the current PC or that of the next
 213    instruction?  The following functions are defined to perform PC-relative
 214    relocations and to undo them (as in the disassembler).  The first function
 215    takes the desired address and the PC of the current instruction and returns
 216    the unencoded value to be stored in the offset field.  The second function
 217    takes the unencoded offset value and the current PC and returns the address.
 218    Note that these functions do not replace the encode/decode functions; the
 219    operands must be encoded/decoded separately.  */
 220
 221 extern int xtensa_operand_isPCRelative (xtensa_operand);
 222
 223 extern uint32 xtensa_operand_do_reloc (xtensa_operand, uint32, uint32);
 224
 225 extern uint32 xtensa_operand_undo_reloc (xtensa_operand, uint32, uint32);
 226
 227 #ifdef __cplusplus
 228 }
 229 #endif
 230 #endif /* XTENSA_LIBISA_H */