gnu/usr.bin/as/README.rich

   1 (This file is under construction.)
   2
   3
   4                  The Code Pedigree of This Directory
   5
   6
   7 This directory contains a big merge of several development lines of
   8 gas as well as a few bug fixes and some configuration that I've added
   9 in order to retain my own sanity.
  10
  11 A little history.
  12
  13 The only common baseline of all versions was gas-1.31.
  14
  15 From 1.31, Intel branched off and added:
  16
  17         support for the Intel 80960 (i960) processor.
  18         support for b.out object files.
  19         some bug fixes.
  20         sloppy mac MPW support
  21         Intel gnu/960 makefiles and version numbering.
  22
  23 Many of the bug fixes found their way into the main development line
  24 prior to 1.36.  ALL intel changes were ifdef'd I80960.  This was good
  25 as it isolated the changes, but bad in that it connected the b.out
  26 support to the i960 support, and bad in that the bug fixes were only
  27 active in the i960+b.out executables of gas, (although most of these
  28 were nicely marked with comments indicating that they were probably
  29 general bug fixes.)
  30
  31 To pick up the main FSF development line again, along the way to 1.36,
  32 several new processors were added, many bugs fixed, and the world was
  33 a somewhat better place in general.
  34
  35 From gas-1.36, Loic at Axis Design (france!) encapsulated object
  36 format specific actions, added coff versions of those encapsulations,
  37 and a config.gas style configuration and Makefile.  This was a big
  38 change and a lot of work.
  39
  40 Then along came the FIRST FSF release of gas-1.37.  I say this because
  41 there have been at least two releases of gas-1.37.  Only two of them
  42 do we care about for this story, so let's call them gas-1.37.1 and
  43 gas-1.37.2.
  44
  45 Here starts the confusion.  Firstly, gas-1.37.1 did not compile.
  46
  47 In the meantime, John Gilmore at Cygnus Support had been hacking
  48 gas-1.37.1.  He got it to compile.  He added support for the AMD 29000
  49 processor.  AND he started encapsulating some of the a.out specific
  50 pieces of code mostly into functions.  AND he rebuilt the relocation
  51 info to be generic.  AND he restructured somewhat so that for a single
  52 host, cross assemblers could be built for all targets in the same
  53 directory.  Useful work but a considerable nuisance because the a29k
  54 changes were not partitioned from the encapsulation changes, the
  55 encapsulation changes were incomplete, and the encapsulation required
  56 functions where alternate structuring might have used macros. Let's
  57 call this version gas-1.37.1+a29k.
  58
  59 By the time gas-1.37.2 was "released", (remember that it TOO was
  60 labelled by FSF as gas-1.37), it compiled, but it also added i860
  61 support and ansi style const declarations.
  62
  63 At this point, Loic rolled his changes into gas-1.37.2.
  64
  65 What I've done.
  66
  67 I collected all the stray versions of gas that sounded relevant to my
  68 goals of cross assembly and alternate object file formats and the FSF
  69 releases from which the stray versions had branched.
  70
  71 I rolled the Intel i960 changes from 1.31 into versions that I call
  72 1.34+i960, 1.36+i960, and then 1.37.1+i960.
  73
  74 Then I merged 1.37.1+i960 with 1.37.1+a29k to produce what I call
  75 1.37.1+i960+a29k or 1.37.3.
  76
  77 From 1.37.3, I pulled in Loic's stuff.  This wasn't easy as Loic's
  78 stuff hit all the same points as John's encapsulations.  Loic's goal
  79 was to split the a.out from coff dependancies for native assembly on
  80 coff, while John's was to split for multiple cross assembly from a
  81 single host.
  82
  83 Loic's config arranged files much like emacs into m-*, etc.  I've
  84 rearranged these somewhat.
  85
  86 Theory:
  87
  88 The goal of the new configuration scheme is to bury all object format,
  89 target processor, and host machine dependancies in object, target, and
  90 host specific files.  That is, to move all #ifdef's out of the gas
  91 common code.
  92
  93 Here's how it works.  There is a .h and a .c file for each object file
  94 format, a .h and a .c file for each target processor, and a .h for
  95 each host.  config.gas creates {sym}links in the current directory to
  96 the appropriate files in the config directory.  config.gas also serves
  97 as a list of triplets {host, target, object-format} that have been
  98 tested at one time or another.  I also recommend that config.gas be
  99 used to document triplet specific notes as to purpose of the triplet,
 100 etc.
 101
 102 Implementation:
 103
 104 host.h is a {sym}link to .../config/xm-yourhost.h.  It is intended to
 105 be used to hide host compiler, system header file, and system library
 106 differences between host machines.  If your host needs actual c source
 107 files, then either: these are generally useful functions, in which
 108 case you should probably build a local library outside of the gas
 109 source tree, or someone, perhaps me, is confused about what is needed
 110 by different hosts.
 111
 112 obj-format.h is a {sym}link to .../config/obj-something.h.  It is intended
 113
 114 All gas .c files include as.h.
 115
 116 as.h #define's "gas", includes host.h, defines a number of gas
 117 specific structures and types, and then includes tp.h, obj.h, and
 118 target-environment.h.
 119
 120 target-environment.h defines a target environment specific
 121 preprocessor flag, eg, TE_SUN, and then includes obj-format.h.
 122
 123 obj-format.h defines an object format specific preprocessor flag, eg,
 124 OBJ_AOUT, OBJ_BOUT, OBJ_COFF, includes "target-processor.h", and then
 125 defines the object specific macros, functions, types, and structures.
 126
 127 target-processor.h
 128
 129 target-processor.
 130
 131 Porting:
 132
 133 There appear to be four major types of ports; new hosts, new target
 134 processors, new object file formats, and new target environments.
 135
 136
 137 -----
 138
 139 reloc now stored internally as generic. (symbols too?) (segment types
 140 vs. names?)
 141
 142 I don't mean to overlook anyone here.  There have also been several
 143 other development lines here that I looked at and elected to bypass.
 144 Specifically, xxx's stabs in coff stuff was particularly tempting.