contrib/binutils/bfd/doc/archures.texi

   1 @section Architectures
   2 BFD keeps one atom in a BFD describing the
   3 architecture of the data attached to the BFD: a pointer to a
   4 @code{bfd_arch_info_type}.
   5
   6 Pointers to structures can be requested independently of a BFD
   7 so that an architecture's information can be interrogated
   8 without access to an open BFD.
   9
  10 The architecture information is provided by each architecture package.
  11 The set of default architectures is selected by the macro
  12 @code{SELECT_ARCHITECTURES}.  This is normally set up in the
  13 @file{config/@var{target}.mt} file of your choice.  If the name is not
  14 defined, then all the architectures supported are included.
  15
  16 When BFD starts up, all the architectures are called with an
  17 initialize method.  It is up to the architecture back end to
  18 insert as many items into the list of architectures as it wants to;
  19 generally this would be one for each machine and one for the
  20 default case (an item with a machine field of 0).
  21
  22 BFD's idea of an architecture is implemented in @file{archures.c}.
  23
  24 @subsection bfd_architecture
  25
  26
  27 @strong{Description}@*
  28 This enum gives the object file's CPU architecture, in a
  29 global sense---i.e., what processor family does it belong to?
  30 Another field indicates which processor within
  31 the family is in use.  The machine gives a number which
  32 distinguishes different versions of the architecture,
  33 containing, for example, 2 and 3 for Intel i960 KA and i960 KB,
  34 and 68020 and 68030 for Motorola 68020 and 68030.
  35 @example
  36 enum bfd_architecture
  37 @{
  38   bfd_arch_unknown,   /* File arch not known.  */
  39   bfd_arch_obscure,   /* Arch known, not one of these.  */
  40   bfd_arch_m68k,      /* Motorola 68xxx */
  41 #define bfd_mach_m68000 1
  42 #define bfd_mach_m68008 2
  43 #define bfd_mach_m68010 3
  44 #define bfd_mach_m68020 4
  45 #define bfd_mach_m68030 5
  46 #define bfd_mach_m68040 6
  47 #define bfd_mach_m68060 7
  48 #define bfd_mach_cpu32  8
  49 #define bfd_mach_mcf5200  9
  50 #define bfd_mach_mcf5206e 10
  51 #define bfd_mach_mcf5307  11
  52 #define bfd_mach_mcf5407  12
  53   bfd_arch_vax,       /* DEC Vax */
  54   bfd_arch_i960,      /* Intel 960 */
  55     /* The order of the following is important.
  56        lower number indicates a machine type that
  57        only accepts a subset of the instructions
  58        available to machines with higher numbers.
  59        The exception is the "ca", which is
  60        incompatible with all other machines except
  61        "core".  */
  62
  63 #define bfd_mach_i960_core      1
  64 #define bfd_mach_i960_ka_sa     2
  65 #define bfd_mach_i960_kb_sb     3
  66 #define bfd_mach_i960_mc        4
  67 #define bfd_mach_i960_xa        5
  68 #define bfd_mach_i960_ca        6
  69 #define bfd_mach_i960_jx        7
  70 #define bfd_mach_i960_hx        8
  71
  72   bfd_arch_or32,      /* OpenRISC 32 */
  73
  74   bfd_arch_a29k,      /* AMD 29000 */
  75   bfd_arch_sparc,     /* SPARC */
  76 #define bfd_mach_sparc                 1
  77 /* The difference between v8plus and v9 is that v9 is a true 64 bit env.  */
  78 #define bfd_mach_sparc_sparclet        2
  79 #define bfd_mach_sparc_sparclite       3
  80 #define bfd_mach_sparc_v8plus          4
  81 #define bfd_mach_sparc_v8plusa         5 /* with ultrasparc add'ns.  */
  82 #define bfd_mach_sparc_sparclite_le    6
  83 #define bfd_mach_sparc_v9              7
  84 #define bfd_mach_sparc_v9a             8 /* with ultrasparc add'ns.  */
  85 #define bfd_mach_sparc_v8plusb         9 /* with cheetah add'ns.  */
  86 #define bfd_mach_sparc_v9b             10 /* with cheetah add'ns.  */
  87 /* Nonzero if MACH has the v9 instruction set.  */
  88 #define bfd_mach_sparc_v9_p(mach) \
  89   ((mach) >= bfd_mach_sparc_v8plus && (mach) <= bfd_mach_sparc_v9b \
  90    && (mach) != bfd_mach_sparc_sparclite_le)
  91   bfd_arch_mips,      /* MIPS Rxxxx */
  92 #define bfd_mach_mips3000              3000
  93 #define bfd_mach_mips3900              3900
  94 #define bfd_mach_mips4000              4000
  95 #define bfd_mach_mips4010              4010
  96 #define bfd_mach_mips4100              4100
  97 #define bfd_mach_mips4111              4111
  98 #define bfd_mach_mips4300              4300
  99 #define bfd_mach_mips4400              4400
 100 #define bfd_mach_mips4600              4600
 101 #define bfd_mach_mips4650              4650
 102 #define bfd_mach_mips5000              5000
 103 #define bfd_mach_mips6000              6000
 104 #define bfd_mach_mips8000              8000
 105 #define bfd_mach_mips10000             10000
 106 #define bfd_mach_mips12000             12000
 107 #define bfd_mach_mips16                16
 108 #define bfd_mach_mips5                 5
 109 #define bfd_mach_mips_sb1              12310201 /* octal 'SB', 01 */
 110 #define bfd_mach_mipsisa32             32
 111 #define bfd_mach_mipsisa64             64
 112   bfd_arch_i386,      /* Intel 386 */
 113 #define bfd_mach_i386_i386 0
 114 #define bfd_mach_i386_i8086 1
 115 #define bfd_mach_i386_i386_intel_syntax 2
 116 #define bfd_mach_x86_64 3
 117 #define bfd_mach_x86_64_intel_syntax 4
 118   bfd_arch_we32k,     /* AT&T WE32xxx */
 119   bfd_arch_tahoe,     /* CCI/Harris Tahoe */
 120   bfd_arch_i860,      /* Intel 860 */
 121   bfd_arch_i370,      /* IBM 360/370 Mainframes */
 122   bfd_arch_romp,      /* IBM ROMP PC/RT */
 123   bfd_arch_alliant,   /* Alliant */
 124   bfd_arch_convex,    /* Convex */
 125   bfd_arch_m88k,      /* Motorola 88xxx */
 126   bfd_arch_pyramid,   /* Pyramid Technology */
 127   bfd_arch_h8300,     /* Hitachi H8/300 */
 128 #define bfd_mach_h8300   1
 129 #define bfd_mach_h8300h  2
 130 #define bfd_mach_h8300s  3
 131   bfd_arch_pdp11,     /* DEC PDP-11 */
 132   bfd_arch_powerpc,   /* PowerPC */
 133 #define bfd_mach_ppc           0
 134 #define bfd_mach_ppc64         1
 135 #define bfd_mach_ppc_403       403
 136 #define bfd_mach_ppc_403gc     4030
 137 #define bfd_mach_ppc_505       505
 138 #define bfd_mach_ppc_601       601
 139 #define bfd_mach_ppc_602       602
 140 #define bfd_mach_ppc_603       603
 141 #define bfd_mach_ppc_ec603e    6031
 142 #define bfd_mach_ppc_604       604
 143 #define bfd_mach_ppc_620       620
 144 #define bfd_mach_ppc_630       630
 145 #define bfd_mach_ppc_750       750
 146 #define bfd_mach_ppc_860       860
 147 #define bfd_mach_ppc_a35       35
 148 #define bfd_mach_ppc_rs64ii    642
 149 #define bfd_mach_ppc_rs64iii   643
 150 #define bfd_mach_ppc_7400      7400
 151   bfd_arch_rs6000,    /* IBM RS/6000 */
 152 #define bfd_mach_rs6k          0
 153 #define bfd_mach_rs6k_rs1      6001
 154 #define bfd_mach_rs6k_rsc      6003
 155 #define bfd_mach_rs6k_rs2      6002
 156   bfd_arch_hppa,      /* HP PA RISC */
 157   bfd_arch_d10v,      /* Mitsubishi D10V */
 158 #define bfd_mach_d10v          0
 159 #define bfd_mach_d10v_ts2      2
 160 #define bfd_mach_d10v_ts3      3
 161   bfd_arch_d30v,      /* Mitsubishi D30V */
 162   bfd_arch_m68hc11,   /* Motorola 68HC11 */
 163   bfd_arch_m68hc12,   /* Motorola 68HC12 */
 164   bfd_arch_z8k,       /* Zilog Z8000 */
 165 #define bfd_mach_z8001         1
 166 #define bfd_mach_z8002         2
 167   bfd_arch_h8500,     /* Hitachi H8/500 */
 168   bfd_arch_sh,        /* Hitachi SH */
 169 #define bfd_mach_sh            0
 170 #define bfd_mach_sh2        0x20
 171 #define bfd_mach_sh_dsp     0x2d
 172 #define bfd_mach_sh3        0x30
 173 #define bfd_mach_sh3_dsp    0x3d
 174 #define bfd_mach_sh3e       0x3e
 175 #define bfd_mach_sh4        0x40
 176 #define bfd_mach_sh5        0x50
 177   bfd_arch_alpha,     /* Dec Alpha */
 178 #define bfd_mach_alpha_ev4  0x10
 179 #define bfd_mach_alpha_ev5  0x20
 180 #define bfd_mach_alpha_ev6  0x30
 181   bfd_arch_arm,       /* Advanced Risc Machines ARM.  */
 182 #define bfd_mach_arm_2         1
 183 #define bfd_mach_arm_2a        2
 184 #define bfd_mach_arm_3         3
 185 #define bfd_mach_arm_3M        4
 186 #define bfd_mach_arm_4         5
 187 #define bfd_mach_arm_4T        6
 188 #define bfd_mach_arm_5         7
 189 #define bfd_mach_arm_5T        8
 190 #define bfd_mach_arm_5TE       9
 191 #define bfd_mach_arm_XScale    10
 192   bfd_arch_ns32k,     /* National Semiconductors ns32000 */
 193   bfd_arch_w65,       /* WDC 65816 */
 194   bfd_arch_tic30,     /* Texas Instruments TMS320C30 */
 195   bfd_arch_tic54x,    /* Texas Instruments TMS320C54X */
 196   bfd_arch_tic80,     /* TI TMS320c80 (MVP) */
 197   bfd_arch_v850,      /* NEC V850 */
 198 #define bfd_mach_v850          0
 199 #define bfd_mach_v850e         'E'
 200 #define bfd_mach_v850ea        'A'
 201   bfd_arch_arc,       /* ARC Cores */
 202 #define bfd_mach_arc_5         0
 203 #define bfd_mach_arc_6         1
 204 #define bfd_mach_arc_7         2
 205 #define bfd_mach_arc_8         3
 206   bfd_arch_m32r,      /* Mitsubishi M32R/D */
 207 #define bfd_mach_m32r          0 /* For backwards compatibility.  */
 208 #define bfd_mach_m32rx         'x'
 209   bfd_arch_mn10200,   /* Matsushita MN10200 */
 210   bfd_arch_mn10300,   /* Matsushita MN10300 */
 211 #define bfd_mach_mn10300               300
 212 #define bfd_mach_am33          330
 213   bfd_arch_fr30,
 214 #define bfd_mach_fr30          0x46523330
 215   bfd_arch_mcore,
 216   bfd_arch_ia64,      /* HP/Intel ia64 */
 217 #define bfd_mach_ia64_elf64    0
 218 #define bfd_mach_ia64_elf32    1
 219   bfd_arch_pj,
 220   bfd_arch_avr,       /* Atmel AVR microcontrollers.  */
 221 #define bfd_mach_avr1          1
 222 #define bfd_mach_avr2          2
 223 #define bfd_mach_avr3          3
 224 #define bfd_mach_avr4          4
 225 #define bfd_mach_avr5          5
 226   bfd_arch_cris,      /* Axis CRIS */
 227   bfd_arch_s390,      /* IBM s390 */
 228 #define bfd_mach_s390_31       0
 229 #define bfd_mach_s390_64       1
 230   bfd_arch_openrisc,  /* OpenRISC */
 231   bfd_arch_mmix,      /* Donald Knuth's educational processor.  */
 232   bfd_arch_xstormy16,
 233 #define bfd_mach_xstormy16     0
 234   bfd_arch_last
 235   @};
 236 @end example
 237
 238 @subsection bfd_arch_info
 239
 240
 241 @strong{Description}@*
 242 This structure contains information on architectures for use
 243 within BFD.
 244 @example
 245
 246 typedef struct bfd_arch_info
 247 @{
 248   int bits_per_word;
 249   int bits_per_address;
 250   int bits_per_byte;
 251   enum bfd_architecture arch;
 252   unsigned long mach;
 253   const char *arch_name;
 254   const char *printable_name;
 255   unsigned int section_align_power;
 256   /* True if this is the default machine for the architecture.
 257      The default arch should be the first entry for an arch so that
 258      all the entries for that arch can be accessed via @code{next}.  */
 259   boolean the_default;
 260   const struct bfd_arch_info * (*compatible)
 261        PARAMS ((const struct bfd_arch_info *a,
 262                 const struct bfd_arch_info *b));
 263
 264   boolean (*scan) PARAMS ((const struct bfd_arch_info *, const char *));
 265
 266   const struct bfd_arch_info *next;
 267 @}
 268 bfd_arch_info_type;
 269
 270 @end example
 271
 272 @findex bfd_printable_name
 273 @subsubsection @code{bfd_printable_name}
 274 @strong{Synopsis}
 275 @example
 276 const char *bfd_printable_name(bfd *abfd);
 277 @end example
 278 @strong{Description}@*
 279 Return a printable string representing the architecture and machine
 280 from the pointer to the architecture info structure.
 281
 282 @findex bfd_scan_arch
 283 @subsubsection @code{bfd_scan_arch}
 284 @strong{Synopsis}
 285 @example
 286 const bfd_arch_info_type *bfd_scan_arch(const char *string);
 287 @end example
 288 @strong{Description}@*
 289 Figure out if BFD supports any cpu which could be described with
 290 the name @var{string}.  Return a pointer to an @code{arch_info}
 291 structure if a machine is found, otherwise NULL.
 292
 293 @findex bfd_arch_list
 294 @subsubsection @code{bfd_arch_list}
 295 @strong{Synopsis}
 296 @example
 297 const char **bfd_arch_list(void);
 298 @end example
 299 @strong{Description}@*
 300 Return a freshly malloced NULL-terminated vector of the names
 301 of all the valid BFD architectures.  Do not modify the names.
 302
 303 @findex bfd_arch_get_compatible
 304 @subsubsection @code{bfd_arch_get_compatible}
 305 @strong{Synopsis}
 306 @example
 307 const bfd_arch_info_type *bfd_arch_get_compatible(
 308     const bfd *abfd,
 309     const bfd *bbfd);
 310 @end example
 311 @strong{Description}@*
 312 Determine whether two BFDs'
 313 architectures and machine types are compatible.  Calculates
 314 the lowest common denominator between the two architectures
 315 and machine types implied by the BFDs and returns a pointer to
 316 an @code{arch_info} structure describing the compatible machine.
 317
 318 @findex bfd_default_arch_struct
 319 @subsubsection @code{bfd_default_arch_struct}
 320 @strong{Description}@*
 321 The @code{bfd_default_arch_struct} is an item of
 322 @code{bfd_arch_info_type} which has been initialized to a fairly
 323 generic state.  A BFD starts life by pointing to this
 324 structure, until the correct back end has determined the real
 325 architecture of the file.
 326 @example
 327 extern const bfd_arch_info_type bfd_default_arch_struct;
 328 @end example
 329
 330 @findex bfd_set_arch_info
 331 @subsubsection @code{bfd_set_arch_info}
 332 @strong{Synopsis}
 333 @example
 334 void bfd_set_arch_info(bfd *abfd, const bfd_arch_info_type *arg);
 335 @end example
 336 @strong{Description}@*
 337 Set the architecture info of @var{abfd} to @var{arg}.
 338
 339 @findex bfd_default_set_arch_mach
 340 @subsubsection @code{bfd_default_set_arch_mach}
 341 @strong{Synopsis}
 342 @example
 343 boolean bfd_default_set_arch_mach(bfd *abfd,
 344     enum bfd_architecture arch,
 345     unsigned long mach);
 346 @end example
 347 @strong{Description}@*
 348 Set the architecture and machine type in BFD @var{abfd}
 349 to @var{arch} and @var{mach}.  Find the correct
 350 pointer to a structure and insert it into the @code{arch_info}
 351 pointer.
 352
 353 @findex bfd_get_arch
 354 @subsubsection @code{bfd_get_arch}
 355 @strong{Synopsis}
 356 @example
 357 enum bfd_architecture bfd_get_arch(bfd *abfd);
 358 @end example
 359 @strong{Description}@*
 360 Return the enumerated type which describes the BFD @var{abfd}'s
 361 architecture.
 362
 363 @findex bfd_get_mach
 364 @subsubsection @code{bfd_get_mach}
 365 @strong{Synopsis}
 366 @example
 367 unsigned long bfd_get_mach(bfd *abfd);
 368 @end example
 369 @strong{Description}@*
 370 Return the long type which describes the BFD @var{abfd}'s
 371 machine.
 372
 373 @findex bfd_arch_bits_per_byte
 374 @subsubsection @code{bfd_arch_bits_per_byte}
 375 @strong{Synopsis}
 376 @example
 377 unsigned int bfd_arch_bits_per_byte(bfd *abfd);
 378 @end example
 379 @strong{Description}@*
 380 Return the number of bits in one of the BFD @var{abfd}'s
 381 architecture's bytes.
 382
 383 @findex bfd_arch_bits_per_address
 384 @subsubsection @code{bfd_arch_bits_per_address}
 385 @strong{Synopsis}
 386 @example
 387 unsigned int bfd_arch_bits_per_address(bfd *abfd);
 388 @end example
 389 @strong{Description}@*
 390 Return the number of bits in one of the BFD @var{abfd}'s
 391 architecture's addresses.
 392
 393 @findex bfd_default_compatible
 394 @subsubsection @code{bfd_default_compatible}
 395 @strong{Synopsis}
 396 @example
 397 const bfd_arch_info_type *bfd_default_compatible
 398    (const bfd_arch_info_type *a,
 399     const bfd_arch_info_type *b);
 400 @end example
 401 @strong{Description}@*
 402 The default function for testing for compatibility.
 403
 404 @findex bfd_default_scan
 405 @subsubsection @code{bfd_default_scan}
 406 @strong{Synopsis}
 407 @example
 408 boolean bfd_default_scan(const struct bfd_arch_info *info, const char *string);
 409 @end example
 410 @strong{Description}@*
 411 The default function for working out whether this is an
 412 architecture hit and a machine hit.
 413
 414 @findex bfd_get_arch_info
 415 @subsubsection @code{bfd_get_arch_info}
 416 @strong{Synopsis}
 417 @example
 418 const bfd_arch_info_type * bfd_get_arch_info(bfd *abfd);
 419 @end example
 420 @strong{Description}@*
 421 Return the architecture info struct in @var{abfd}.
 422
 423 @findex bfd_lookup_arch
 424 @subsubsection @code{bfd_lookup_arch}
 425 @strong{Synopsis}
 426 @example
 427 const bfd_arch_info_type *bfd_lookup_arch
 428    (enum bfd_architecture
 429     arch,
 430     unsigned long machine);
 431 @end example
 432 @strong{Description}@*
 433 Look for the architecure info structure which matches the
 434 arguments @var{arch} and @var{machine}. A machine of 0 matches the
 435 machine/architecture structure which marks itself as the
 436 default.
 437
 438 @findex bfd_printable_arch_mach
 439 @subsubsection @code{bfd_printable_arch_mach}
 440 @strong{Synopsis}
 441 @example
 442 const char *bfd_printable_arch_mach
 443    (enum bfd_architecture arch, unsigned long machine);
 444 @end example
 445 @strong{Description}@*
 446 Return a printable string representing the architecture and
 447 machine type.
 448
 449 This routine is depreciated.
 450
 451 @findex bfd_octets_per_byte
 452 @subsubsection @code{bfd_octets_per_byte}
 453 @strong{Synopsis}
 454 @example
 455 unsigned int bfd_octets_per_byte(bfd *abfd);
 456 @end example
 457 @strong{Description}@*
 458 Return the number of octets (8-bit quantities) per target byte
 459 (minimum addressable unit).  In most cases, this will be one, but some
 460 DSP targets have 16, 32, or even 48 bits per byte.
 461
 462 @findex bfd_arch_mach_octets_per_byte
 463 @subsubsection @code{bfd_arch_mach_octets_per_byte}
 464 @strong{Synopsis}
 465 @example
 466 unsigned int bfd_arch_mach_octets_per_byte(enum bfd_architecture arch,
 467     unsigned long machine);
 468 @end example
 469 @strong{Description}@*
 470 See bfd_octets_per_byte.
 471
 472 This routine is provided for those cases where a bfd * is not
 473 available
 474