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