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 #define bfd_mach_mcf528x  13
  54   bfd_arch_vax,       /* DEC Vax */
  55   bfd_arch_i960,      /* Intel 960 */
  56     /* The order of the following is important.
  57        lower number indicates a machine type that
  58        only accepts a subset of the instructions
  59        available to machines with higher numbers.
  60        The exception is the "ca", which is
  61        incompatible with all other machines except
  62        "core".  */
  63
  64 #define bfd_mach_i960_core      1
  65 #define bfd_mach_i960_ka_sa     2
  66 #define bfd_mach_i960_kb_sb     3
  67 #define bfd_mach_i960_mc        4
  68 #define bfd_mach_i960_xa        5
  69 #define bfd_mach_i960_ca        6
  70 #define bfd_mach_i960_jx        7
  71 #define bfd_mach_i960_hx        8
  72
  73   bfd_arch_or32,      /* OpenRISC 32 */
  74
  75   bfd_arch_a29k,      /* AMD 29000 */
  76   bfd_arch_sparc,     /* SPARC */
  77 #define bfd_mach_sparc                 1
  78 /* The difference between v8plus and v9 is that v9 is a true 64 bit env.  */
  79 #define bfd_mach_sparc_sparclet        2
  80 #define bfd_mach_sparc_sparclite       3
  81 #define bfd_mach_sparc_v8plus          4
  82 #define bfd_mach_sparc_v8plusa         5 /* with ultrasparc add'ns.  */
  83 #define bfd_mach_sparc_sparclite_le    6
  84 #define bfd_mach_sparc_v9              7
  85 #define bfd_mach_sparc_v9a             8 /* with ultrasparc add'ns.  */
  86 #define bfd_mach_sparc_v8plusb         9 /* with cheetah add'ns.  */
  87 #define bfd_mach_sparc_v9b             10 /* with cheetah add'ns.  */
  88 /* Nonzero if MACH has the v9 instruction set.  */
  89 #define bfd_mach_sparc_v9_p(mach) \
  90   ((mach) >= bfd_mach_sparc_v8plus && (mach) <= bfd_mach_sparc_v9b \
  91    && (mach) != bfd_mach_sparc_sparclite_le)
  92   bfd_arch_mips,      /* MIPS Rxxxx */
  93 #define bfd_mach_mips3000              3000
  94 #define bfd_mach_mips3900              3900
  95 #define bfd_mach_mips4000              4000
  96 #define bfd_mach_mips4010              4010
  97 #define bfd_mach_mips4100              4100
  98 #define bfd_mach_mips4111              4111
  99 #define bfd_mach_mips4120              4120
 100 #define bfd_mach_mips4300              4300
 101 #define bfd_mach_mips4400              4400
 102 #define bfd_mach_mips4600              4600
 103 #define bfd_mach_mips4650              4650
 104 #define bfd_mach_mips5000              5000
 105 #define bfd_mach_mips5400              5400
 106 #define bfd_mach_mips5500              5500
 107 #define bfd_mach_mips6000              6000
 108 #define bfd_mach_mips7000              7000
 109 #define bfd_mach_mips8000              8000
 110 #define bfd_mach_mips10000             10000
 111 #define bfd_mach_mips12000             12000
 112 #define bfd_mach_mips16                16
 113 #define bfd_mach_mips5                 5
 114 #define bfd_mach_mips_sb1              12310201 /* octal 'SB', 01 */
 115 #define bfd_mach_mipsisa32             32
 116 #define bfd_mach_mipsisa32r2           33
 117 #define bfd_mach_mipsisa64             64
 118 #define bfd_mach_mipsisa64r2           65
 119   bfd_arch_i386,      /* Intel 386 */
 120 #define bfd_mach_i386_i386 1
 121 #define bfd_mach_i386_i8086 2
 122 #define bfd_mach_i386_i386_intel_syntax 3
 123 #define bfd_mach_x86_64 64
 124 #define bfd_mach_x86_64_intel_syntax 65
 125   bfd_arch_we32k,     /* AT&T WE32xxx */
 126   bfd_arch_tahoe,     /* CCI/Harris Tahoe */
 127   bfd_arch_i860,      /* Intel 860 */
 128   bfd_arch_i370,      /* IBM 360/370 Mainframes */
 129   bfd_arch_romp,      /* IBM ROMP PC/RT */
 130   bfd_arch_alliant,   /* Alliant */
 131   bfd_arch_convex,    /* Convex */
 132   bfd_arch_m88k,      /* Motorola 88xxx */
 133   bfd_arch_m98k,      /* Motorola 98xxx */
 134   bfd_arch_pyramid,   /* Pyramid Technology */
 135   bfd_arch_h8300,     /* Renesas H8/300 (formerly Hitachi H8/300) */
 136 #define bfd_mach_h8300    1
 137 #define bfd_mach_h8300h   2
 138 #define bfd_mach_h8300s   3
 139 #define bfd_mach_h8300hn  4
 140 #define bfd_mach_h8300sn  5
 141 #define bfd_mach_h8300sx  6
 142 #define bfd_mach_h8300sxn 7
 143   bfd_arch_pdp11,     /* DEC PDP-11 */
 144   bfd_arch_powerpc,   /* PowerPC */
 145 #define bfd_mach_ppc           32
 146 #define bfd_mach_ppc64         64
 147 #define bfd_mach_ppc_403       403
 148 #define bfd_mach_ppc_403gc     4030
 149 #define bfd_mach_ppc_505       505
 150 #define bfd_mach_ppc_601       601
 151 #define bfd_mach_ppc_602       602
 152 #define bfd_mach_ppc_603       603
 153 #define bfd_mach_ppc_ec603e    6031
 154 #define bfd_mach_ppc_604       604
 155 #define bfd_mach_ppc_620       620
 156 #define bfd_mach_ppc_630       630
 157 #define bfd_mach_ppc_750       750
 158 #define bfd_mach_ppc_860       860
 159 #define bfd_mach_ppc_a35       35
 160 #define bfd_mach_ppc_rs64ii    642
 161 #define bfd_mach_ppc_rs64iii   643
 162 #define bfd_mach_ppc_7400      7400
 163 #define bfd_mach_ppc_e500      500
 164   bfd_arch_rs6000,    /* IBM RS/6000 */
 165 #define bfd_mach_rs6k          6000
 166 #define bfd_mach_rs6k_rs1      6001
 167 #define bfd_mach_rs6k_rsc      6003
 168 #define bfd_mach_rs6k_rs2      6002
 169   bfd_arch_hppa,      /* HP PA RISC */
 170 #define bfd_mach_hppa10        10
 171 #define bfd_mach_hppa11        11
 172 #define bfd_mach_hppa20        20
 173 #define bfd_mach_hppa20w       25
 174   bfd_arch_d10v,      /* Mitsubishi D10V */
 175 #define bfd_mach_d10v          1
 176 #define bfd_mach_d10v_ts2      2
 177 #define bfd_mach_d10v_ts3      3
 178   bfd_arch_d30v,      /* Mitsubishi D30V */
 179   bfd_arch_dlx,       /* DLX */
 180   bfd_arch_m68hc11,   /* Motorola 68HC11 */
 181   bfd_arch_m68hc12,   /* Motorola 68HC12 */
 182 #define bfd_mach_m6812_default 0
 183 #define bfd_mach_m6812         1
 184 #define bfd_mach_m6812s        2
 185   bfd_arch_z8k,       /* Zilog Z8000 */
 186 #define bfd_mach_z8001         1
 187 #define bfd_mach_z8002         2
 188   bfd_arch_h8500,     /* Renesas H8/500 (formerly Hitachi H8/500) */
 189   bfd_arch_sh,        /* Renesas / SuperH SH (formerly Hitachi SH) */
 190 #define bfd_mach_sh            1
 191 #define bfd_mach_sh2        0x20
 192 #define bfd_mach_sh_dsp     0x2d
 193 #define bfd_mach_sh2e       0x2e
 194 #define bfd_mach_sh3        0x30
 195 #define bfd_mach_sh3_dsp    0x3d
 196 #define bfd_mach_sh3e       0x3e
 197 #define bfd_mach_sh4        0x40
 198 #define bfd_mach_sh4_nofpu  0x41
 199 #define bfd_mach_sh4a       0x4a
 200 #define bfd_mach_sh4a_nofpu 0x4b
 201 #define bfd_mach_sh4al_dsp  0x4d
 202 #define bfd_mach_sh5        0x50
 203   bfd_arch_alpha,     /* Dec Alpha */
 204 #define bfd_mach_alpha_ev4  0x10
 205 #define bfd_mach_alpha_ev5  0x20
 206 #define bfd_mach_alpha_ev6  0x30
 207   bfd_arch_arm,       /* Advanced Risc Machines ARM.  */
 208 #define bfd_mach_arm_unknown   0
 209 #define bfd_mach_arm_2         1
 210 #define bfd_mach_arm_2a        2
 211 #define bfd_mach_arm_3         3
 212 #define bfd_mach_arm_3M        4
 213 #define bfd_mach_arm_4         5
 214 #define bfd_mach_arm_4T        6
 215 #define bfd_mach_arm_5         7
 216 #define bfd_mach_arm_5T        8
 217 #define bfd_mach_arm_5TE       9
 218 #define bfd_mach_arm_XScale    10
 219 #define bfd_mach_arm_ep9312    11
 220 #define bfd_mach_arm_iWMMXt    12
 221   bfd_arch_ns32k,     /* National Semiconductors ns32000 */
 222   bfd_arch_w65,       /* WDC 65816 */
 223   bfd_arch_tic30,     /* Texas Instruments TMS320C30 */
 224   bfd_arch_tic4x,     /* Texas Instruments TMS320C3X/4X */
 225 #define bfd_mach_tic3x         30
 226 #define bfd_mach_tic4x         40
 227   bfd_arch_tic54x,    /* Texas Instruments TMS320C54X */
 228   bfd_arch_tic80,     /* TI TMS320c80 (MVP) */
 229   bfd_arch_v850,      /* NEC V850 */
 230 #define bfd_mach_v850          1
 231 #define bfd_mach_v850e         'E'
 232 #define bfd_mach_v850e1        '1'
 233   bfd_arch_arc,       /* ARC Cores */
 234 #define bfd_mach_arc_5         5
 235 #define bfd_mach_arc_6         6
 236 #define bfd_mach_arc_7         7
 237 #define bfd_mach_arc_8         8
 238   bfd_arch_m32r,      /* Renesas M32R (formerly Mitsubishi M32R/D) */
 239 #define bfd_mach_m32r          1 /* For backwards compatibility.  */
 240 #define bfd_mach_m32rx         'x'
 241 #define bfd_mach_m32r2         '2'
 242   bfd_arch_mn10200,   /* Matsushita MN10200 */
 243   bfd_arch_mn10300,   /* Matsushita MN10300 */
 244 #define bfd_mach_mn10300               300
 245 #define bfd_mach_am33          330
 246 #define bfd_mach_am33_2        332
 247   bfd_arch_fr30,
 248 #define bfd_mach_fr30          0x46523330
 249   bfd_arch_frv,
 250 #define bfd_mach_frv           1
 251 #define bfd_mach_frvsimple     2
 252 #define bfd_mach_fr300         300
 253 #define bfd_mach_fr400         400
 254 #define bfd_mach_frvtomcat     499     /* fr500 prototype */
 255 #define bfd_mach_fr500         500
 256 #define bfd_mach_fr550         550
 257   bfd_arch_mcore,
 258   bfd_arch_ia64,      /* HP/Intel ia64 */
 259 #define bfd_mach_ia64_elf64    64
 260 #define bfd_mach_ia64_elf32    32
 261   bfd_arch_ip2k,      /* Ubicom IP2K microcontrollers. */
 262 #define bfd_mach_ip2022        1
 263 #define bfd_mach_ip2022ext     2
 264  bfd_arch_iq2000,     /* Vitesse IQ2000.  */
 265 #define bfd_mach_iq2000        1
 266 #define bfd_mach_iq10          2
 267   bfd_arch_pj,
 268   bfd_arch_avr,       /* Atmel AVR microcontrollers.  */
 269 #define bfd_mach_avr1          1
 270 #define bfd_mach_avr2          2
 271 #define bfd_mach_avr3          3
 272 #define bfd_mach_avr4          4
 273 #define bfd_mach_avr5          5
 274   bfd_arch_cris,      /* Axis CRIS */
 275   bfd_arch_s390,      /* IBM s390 */
 276 #define bfd_mach_s390_31       31
 277 #define bfd_mach_s390_64       64
 278   bfd_arch_openrisc,  /* OpenRISC */
 279   bfd_arch_mmix,      /* Donald Knuth's educational processor.  */
 280   bfd_arch_xstormy16,
 281 #define bfd_mach_xstormy16     1
 282   bfd_arch_msp430,    /* Texas Instruments MSP430 architecture.  */
 283 #define bfd_mach_msp11          11
 284 #define bfd_mach_msp110         110
 285 #define bfd_mach_msp12          12
 286 #define bfd_mach_msp13          13
 287 #define bfd_mach_msp14          14
 288 #define bfd_mach_msp15          15
 289 #define bfd_mach_msp16          16
 290 #define bfd_mach_msp31          31
 291 #define bfd_mach_msp32          32
 292 #define bfd_mach_msp33          33
 293 #define bfd_mach_msp41          41
 294 #define bfd_mach_msp42          42
 295 #define bfd_mach_msp43          43
 296 #define bfd_mach_msp44          44
 297   bfd_arch_xtensa,    /* Tensilica's Xtensa cores.  */
 298 #define bfd_mach_xtensa        1
 299   bfd_arch_last
 300   @};
 301 @end example
 302
 303 @subsection bfd_arch_info
 304
 305
 306 @strong{Description}@*
 307 This structure contains information on architectures for use
 308 within BFD.
 309 @example
 310
 311 typedef struct bfd_arch_info
 312 @{
 313   int bits_per_word;
 314   int bits_per_address;
 315   int bits_per_byte;
 316   enum bfd_architecture arch;
 317   unsigned long mach;
 318   const char *arch_name;
 319   const char *printable_name;
 320   unsigned int section_align_power;
 321   /* TRUE if this is the default machine for the architecture.
 322      The default arch should be the first entry for an arch so that
 323      all the entries for that arch can be accessed via @code{next}.  */
 324   bfd_boolean the_default;
 325   const struct bfd_arch_info * (*compatible)
 326     (const struct bfd_arch_info *a, const struct bfd_arch_info *b);
 327
 328   bfd_boolean (*scan) (const struct bfd_arch_info *, const char *);
 329
 330   const struct bfd_arch_info *next;
 331 @}
 332 bfd_arch_info_type;
 333
 334 @end example
 335
 336 @findex bfd_printable_name
 337 @subsubsection @code{bfd_printable_name}
 338 @strong{Synopsis}
 339 @example
 340 const char *bfd_printable_name (bfd *abfd);
 341 @end example
 342 @strong{Description}@*
 343 Return a printable string representing the architecture and machine
 344 from the pointer to the architecture info structure.
 345
 346 @findex bfd_scan_arch
 347 @subsubsection @code{bfd_scan_arch}
 348 @strong{Synopsis}
 349 @example
 350 const bfd_arch_info_type *bfd_scan_arch (const char *string);
 351 @end example
 352 @strong{Description}@*
 353 Figure out if BFD supports any cpu which could be described with
 354 the name @var{string}.  Return a pointer to an @code{arch_info}
 355 structure if a machine is found, otherwise NULL.
 356
 357 @findex bfd_arch_list
 358 @subsubsection @code{bfd_arch_list}
 359 @strong{Synopsis}
 360 @example
 361 const char **bfd_arch_list (void);
 362 @end example
 363 @strong{Description}@*
 364 Return a freshly malloced NULL-terminated vector of the names
 365 of all the valid BFD architectures.  Do not modify the names.
 366
 367 @findex bfd_arch_get_compatible
 368 @subsubsection @code{bfd_arch_get_compatible}
 369 @strong{Synopsis}
 370 @example
 371 const bfd_arch_info_type *bfd_arch_get_compatible
 372    (const bfd *abfd, const bfd *bbfd, bfd_boolean accept_unknowns);
 373 @end example
 374 @strong{Description}@*
 375 Determine whether two BFDs' architectures and machine types
 376 are compatible.  Calculates the lowest common denominator
 377 between the two architectures and machine types implied by
 378 the BFDs and returns a pointer to an @code{arch_info} structure
 379 describing the compatible machine.
 380
 381 @findex bfd_default_arch_struct
 382 @subsubsection @code{bfd_default_arch_struct}
 383 @strong{Description}@*
 384 The @code{bfd_default_arch_struct} is an item of
 385 @code{bfd_arch_info_type} which has been initialized to a fairly
 386 generic state.  A BFD starts life by pointing to this
 387 structure, until the correct back end has determined the real
 388 architecture of the file.
 389 @example
 390 extern const bfd_arch_info_type bfd_default_arch_struct;
 391 @end example
 392
 393 @findex bfd_set_arch_info
 394 @subsubsection @code{bfd_set_arch_info}
 395 @strong{Synopsis}
 396 @example
 397 void bfd_set_arch_info (bfd *abfd, const bfd_arch_info_type *arg);
 398 @end example
 399 @strong{Description}@*
 400 Set the architecture info of @var{abfd} to @var{arg}.
 401
 402 @findex bfd_default_set_arch_mach
 403 @subsubsection @code{bfd_default_set_arch_mach}
 404 @strong{Synopsis}
 405 @example
 406 bfd_boolean bfd_default_set_arch_mach
 407    (bfd *abfd, enum bfd_architecture arch, unsigned long mach);
 408 @end example
 409 @strong{Description}@*
 410 Set the architecture and machine type in BFD @var{abfd}
 411 to @var{arch} and @var{mach}.  Find the correct
 412 pointer to a structure and insert it into the @code{arch_info}
 413 pointer.
 414
 415 @findex bfd_get_arch
 416 @subsubsection @code{bfd_get_arch}
 417 @strong{Synopsis}
 418 @example
 419 enum bfd_architecture bfd_get_arch (bfd *abfd);
 420 @end example
 421 @strong{Description}@*
 422 Return the enumerated type which describes the BFD @var{abfd}'s
 423 architecture.
 424
 425 @findex bfd_get_mach
 426 @subsubsection @code{bfd_get_mach}
 427 @strong{Synopsis}
 428 @example
 429 unsigned long bfd_get_mach (bfd *abfd);
 430 @end example
 431 @strong{Description}@*
 432 Return the long type which describes the BFD @var{abfd}'s
 433 machine.
 434
 435 @findex bfd_arch_bits_per_byte
 436 @subsubsection @code{bfd_arch_bits_per_byte}
 437 @strong{Synopsis}
 438 @example
 439 unsigned int bfd_arch_bits_per_byte (bfd *abfd);
 440 @end example
 441 @strong{Description}@*
 442 Return the number of bits in one of the BFD @var{abfd}'s
 443 architecture's bytes.
 444
 445 @findex bfd_arch_bits_per_address
 446 @subsubsection @code{bfd_arch_bits_per_address}
 447 @strong{Synopsis}
 448 @example
 449 unsigned int bfd_arch_bits_per_address (bfd *abfd);
 450 @end example
 451 @strong{Description}@*
 452 Return the number of bits in one of the BFD @var{abfd}'s
 453 architecture's addresses.
 454
 455 @findex bfd_default_compatible
 456 @subsubsection @code{bfd_default_compatible}
 457 @strong{Synopsis}
 458 @example
 459 const bfd_arch_info_type *bfd_default_compatible
 460    (const bfd_arch_info_type *a, const bfd_arch_info_type *b);
 461 @end example
 462 @strong{Description}@*
 463 The default function for testing for compatibility.
 464
 465 @findex bfd_default_scan
 466 @subsubsection @code{bfd_default_scan}
 467 @strong{Synopsis}
 468 @example
 469 bfd_boolean bfd_default_scan
 470    (const struct bfd_arch_info *info, const char *string);
 471 @end example
 472 @strong{Description}@*
 473 The default function for working out whether this is an
 474 architecture hit and a machine hit.
 475
 476 @findex bfd_get_arch_info
 477 @subsubsection @code{bfd_get_arch_info}
 478 @strong{Synopsis}
 479 @example
 480 const bfd_arch_info_type *bfd_get_arch_info (bfd *abfd);
 481 @end example
 482 @strong{Description}@*
 483 Return the architecture info struct in @var{abfd}.
 484
 485 @findex bfd_lookup_arch
 486 @subsubsection @code{bfd_lookup_arch}
 487 @strong{Synopsis}
 488 @example
 489 const bfd_arch_info_type *bfd_lookup_arch
 490    (enum bfd_architecture arch, unsigned long machine);
 491 @end example
 492 @strong{Description}@*
 493 Look for the architecture info structure which matches the
 494 arguments @var{arch} and @var{machine}. A machine of 0 matches the
 495 machine/architecture structure which marks itself as the
 496 default.
 497
 498 @findex bfd_printable_arch_mach
 499 @subsubsection @code{bfd_printable_arch_mach}
 500 @strong{Synopsis}
 501 @example
 502 const char *bfd_printable_arch_mach
 503    (enum bfd_architecture arch, unsigned long machine);
 504 @end example
 505 @strong{Description}@*
 506 Return a printable string representing the architecture and
 507 machine type.
 508
 509 This routine is depreciated.
 510
 511 @findex bfd_octets_per_byte
 512 @subsubsection @code{bfd_octets_per_byte}
 513 @strong{Synopsis}
 514 @example
 515 unsigned int bfd_octets_per_byte (bfd *abfd);
 516 @end example
 517 @strong{Description}@*
 518 Return the number of octets (8-bit quantities) per target byte
 519 (minimum addressable unit).  In most cases, this will be one, but some
 520 DSP targets have 16, 32, or even 48 bits per byte.
 521
 522 @findex bfd_arch_mach_octets_per_byte
 523 @subsubsection @code{bfd_arch_mach_octets_per_byte}
 524 @strong{Synopsis}
 525 @example
 526 unsigned int bfd_arch_mach_octets_per_byte
 527    (enum bfd_architecture arch, unsigned long machine);
 528 @end example
 529 @strong{Description}@*
 530 See bfd_octets_per_byte.
 531
 532 This routine is provided for those cases where a bfd * is not
 533 available
 534