rdoff/README

   1 RDOFF Utils v0.3
   2 ================
   3
   4 The files contained in this directory are the C source code of a set
   5 of tools (and general purpose library files) for the manipulation of
   6 RDOFF version 2 object files. Note that these programs (with the
   7 exception of 'rdfdump') will NOT work with version 1 object files. Version 1
   8 of RDOFF is no longer supported. You should be using v2 instead now.
   9
  10 There is also a 'Changes' file, which documents the differences between
  11 RDOFF 1 and 2, and an 'rdoff2.txt' file, with complete documentation for the
  12 new format.
  13
  14 Here is a brief summary of the programs' usage:
  15
  16 rdfdump
  17 =======
  18
  19 This tool prints a list of the header records in an RDOFF object in
  20 human-readable form, and optionally prints a hex dump of the contents
  21 of the segments.
  22
  23 Usage:
  24         rdfdump [-v] filename
  25
  26 The -v flag specifies that the hex dump (see above) should be printed.
  27
  28 Changes from previous versions:
  29
  30 * rdfdump supports both version 1 and 2 of RDOFF.
  31 * rdfdump now gives warnings if the RDOFF2 format is violated (it
  32   looks for incorrect lengths for header records, and checks the
  33   overall length count at the start of the file)
  34
  35 ldrdf
  36 =====
  37
  38 This tool is a version of unix 'ld' (or DOS 'link') for use with RDOFF
  39 files. It is capable of linking RDOFF objects, and libraries produced
  40 with the 'rdlib' utility discussed below.
  41
  42 In normal usage, its command line takes the form:
  43
  44         ldrdf [-o output-file] object files [-llibrary ...]
  45
  46 Libraries must be specified with their path as no search is performed.
  47 Modules in libraries are not linked to the program unless they are
  48 referred to.
  49
  50 Most of its options are not implemented, but those that are are listed here:
  51
  52    -v   increase verbosity level. Currently 4 verbosity levels are
  53         available: default (which only prints error information), normal
  54         (which prints information about the produced object, -v), medium
  55         (which prints information about what the program is doing, -v -v)
  56         and high (which prints all available information, -v -v -v).
  57
  58    -p   change alignment value to which multiple segments combigned into
  59         a single segment should be aligned (must be either 1, 2, 4, 8,
  60         16, 32 or 256. Default is 16).
  61
  62 The default output filename is 'aout.rdx'.
  63
  64 rdx
  65 ===
  66
  67 This program simply loads and executes an RDOFF object, by calling
  68 '_main', which it expects to be a C-style function, which will accept
  69 two parameters, argc and argv in normal C style.
  70
  71 rdflib
  72 ======
  73
  74 This program creates a library file for use with ldrdf.
  75
  76 It is supplied with a shell script 'makelib' which should probably be used
  77 to create libraries.
  78
  79 Usage:
  80         rdflib command library [optional arguments]
  81
  82 Valid commands are:
  83
  84         c       Create (or truncate) the library
  85         a       Add a module (requires a filename and a name to give the
  86                 module, ie 'rdflib a libc.rdl strcpy.rdf strcpy' puts the
  87                 file 'strcpy.rdf' into 'libc.rdl', and calls it 'strcpy'.
  88         x       Extract (arguments are the opposite to the 'a' command,
  89                 ie you'd do 'rdflib x libc.rdl strcpy strcpy.rdf to get
  90                 a copy of strcpy.rdf back out again...)
  91         t       List modules in the library
  92
  93 A remove command will be added soon (it is already documented
  94 as existing, but I haven't had time to implement it... if anyone
  95 else wants to do this, they're welcome to. The file format should be
  96 amply documented in the source code... look at 'rdflib.c' and 'rdlib.c',
  97 and the relevant sections of 'ldrdf.c' to see how libraries can be
  98 handled).
  99
 100 Library functions
 101 =================
 102
 103 The files 'rdoff.c', 'rdoff.h', 'rdfload.c' and 'rdfload.h' contain
 104 code which you may find useful. They retain the same interface as
 105 the previous version, so any code that used them previously should
 106 still work OK (maybe). 'rdoff.c' contains at the top a line:
 107
 108 #define STRICT_ERRORS
 109
 110 Comment this line out if you wish to use record types other than the
 111 7 predefined types; it will then not report such records as an error,
 112 but accept them gracefully, and read them byte for byte into
 113 a 'generic record' (see the definition of GenericRec in 'rdoff.h').
 114
 115 If you are using these functions to write RDF modules (rather than
 116 just reading them), then please note the existance of a new function
 117 'rdfaddsegment(rdf_headerbuf,long)'. This must be called once for
 118 each segment in your object, to tell the header writing functions
 119 how long the segment is.
 120
 121 BUGS
 122 ====
 123
 124 This product has recently undergone a major revision, and as such there
 125 are probably several bugs left over from the testing phase (although the
 126 previous version had quite a few that have now been fixed!). Could you
 127 please report any bugs to me at the address below, including the following
 128 information:
 129
 130   - A description of the bug
 131   - What you think the program should be doing
 132   - Which programs you are using
 133   - Which operating system you are using, and which C compiler was used to
 134     compile the programs (or state that the pre-compiled versions were used).
 135   - If appropriate, any of the following:
 136     * source code (preferably cut down to a minimum that will still assemble
 137       and show the bug)
 138     * the output of rdfdump on produced modules (or send the module if the
 139       problem is in code generated)
 140     * exact descriptions of error messages/symptoms/etc
 141
 142 TODO
 143 ====
 144
 145 There are still various things unimplemented that I would like to add.
 146 If you want to find out what these are, search near the top of each *.c
 147 file for a comment containing the word 'TODO'. A brief list is given here:
 148
 149 - Improve the performace of ldrdf (there are several enhancements I can think
 150   of that wouldn't be too hard to add)
 151 - Stop assuming that we're on a little endian machine
 152 - Make everything work with both formats (?)
 153 - Add extra functions to ldrdf (strip symbols/keep symbol list)
 154 - Check for more bugs
 155
 156 One last thing I have to say: good luck! Whatever it is that you want to use
 157 RDOFF for, I hope its a success.  People out there are using it for many
 158 diverse applications, from operating system boot-loaders to loadable modules
 159 in games.  Whatever your application is, I hope that it works, and that you
 160 have a good time writing it.
 161
 162
 163
 164 Julian Hall <jules@earthcorp.com>