diff options
Diffstat (limited to 'rdoff/doc')
| -rw-r--r-- | rdoff/doc/Makefile | 37 | ||||
| -rw-r--r-- | rdoff/doc/rdoff.texi | 137 | ||||
| -rw-r--r-- | rdoff/doc/v1-v2.txt | 62 |
3 files changed, 236 insertions, 0 deletions
diff --git a/rdoff/doc/Makefile b/rdoff/doc/Makefile new file mode 100644 index 0000000..e4f24f5 --- /dev/null +++ b/rdoff/doc/Makefile @@ -0,0 +1,37 @@ +# +# Make info documentation +# + +AUXFILES = *.aux *.cp *.fn *.ky *.log *.pg *.toc *.tp *.vr *.dvi + +SRCS = rdoff.texi +OUTS = rdoff.info rdoff.html rdoff.ps rdoff.pdf + + +## Implicit rules +%.html : %.texi + makeinfo --html $< + +%.dvi : %.texi + texi2dvi $< + +%.ps: %.dvi + dvips $< + +%.pdf: %.dvi + dvipdf $< + + +## Explicit rules +all: info + +info: rdoff.info + +html: rdoff.html + +ps: rdoff.ps + +pdf: rdoff.pdf + +clean: + rm -f $(OUTS) $(AUXFILES) diff --git a/rdoff/doc/rdoff.texi b/rdoff/doc/rdoff.texi new file mode 100644 index 0000000..4431287 --- /dev/null +++ b/rdoff/doc/rdoff.texi @@ -0,0 +1,137 @@ +\input texinfo @c -*-texinfo-*- +@c %**start of header +@setfilename rdoff.info +@settitle Relocatable Dynamic Object File Format (RDOFF) +@afourpaper +@c %**end of header + +@titlepage +@title Relocatable Dynamic Object File Format (RDOFF) +@author Yuri Zaporogets @email{yuriz@@ukr.net} +@author Julian Hall @email{jules@@dsf.org.uk} +@end titlepage + +@ifinfo +Copyright @copyright{} 2002-2004 Netwide Assembler Project. +Written by Yuri Zaporogets @email{yuriz@@users.sf.net} +Based on various sources and notes written by Julian Hall @email{jules@@dsf.org.uk} +Distributed under GNU documentation license. +@end ifinfo + +@ifnottex +@node Top, Overview, (dir), (dir) +@top RDOFF + +RDOFF is a Relocatable Dynamic Object File Format. + +@end ifnottex + +@menu +* Overview:: Introduction. +* Structure:: Structure of RDOFF file. +* Utilities:: Description of RDOFF utilities. +@end menu + +@node Overview +@chapter Introduction + +RDOFF was designed initially to test the object-file production +interface to NASM. It soon became apparent that it could be enhanced +for use in serious applications due to its simplicity; code to load +and execute an RDOFF object module is very simple. It also contains +enhancements to allow it to be linked with a dynamic link library at +either run- or load- time, depending on how complex you wish to make +your loader. + +@node Structure +@chapter Structure of RDOFF file + +RDOFF module consists of three parts: + +@itemize +@item Master header +@item Header (may be omited) +@item Sections +@end itemize + +@dfn{Master header} contains signature, version and size information. + +@dfn{Header} consists of zero or more @ref{Records, records}. + +@dfn{Sections} represent actual contents of the file. Each section is prepended +by a section header. + +@node Records, , ,Structure +@section Records that may appear in RDOFF header + +@menu +* Relocation:: Relocation records. +* Import:: Declaring external symbols. +* Export:: Declaring public and exported symbols. +* DLL:: Specifying a run-time library name. +* BSS:: Reserving space in BSS section. +* Segment relocation:: Complexity of relocation in segmented systems. +* Far import:: External 'far' symbols. +* Module name:: Specifying module name. +* Common variable:: Declaring common variables. +* Generic record:: Embedding general-purpose data into the header. +@end menu + +@node Relocation +@subsection Relocation records + +@node Import +@subsection Declaring external and imported symbols + +@node Export +@subsection Declaring public and exported symbols + +@node DLL +@subsection Specifying a run-time library name + +@node BSS +@subsection Reserving space in BSS section + +@node Segment relocation +@subsection Complexity of relocation in segmented systems + +@node Far import +@subsection External 'far' symbols. + +@node Module name +@subsection Specifying module name. + +@node Common variable +@subsection Declaring common variables. + +@node Generic record +@subsection Embedding general-purpose data into the header. + + +@node Utilities +@chapter RDOFF utilities + +@menu +* rdfdump:: Dump the contents of RDOFF file. +* ldrdf:: RDOFF linker. +* rdflib:: RDOFF librarian. +* rdlar:: New RDOFF librarian/archiver. +* rdx:: Load and execute RDOFF module. +@end menu + +@node rdfdump +@section @command{rdfdump} - dump the contents of RDOFF file + +@node ldrdf +@section @command{ldrdf} - RDOFF linker + +@node rdflib +@section @command{rdflib} - RDOFF librarian + +@node rdlar +@section @command{rdlar} - new RDOFF librarian/archiver + +@node rdx +@section @command{rdx} - load and execute RDOFF module + +@bye diff --git a/rdoff/doc/v1-v2.txt b/rdoff/doc/v1-v2.txt new file mode 100644 index 0000000..800896b --- /dev/null +++ b/rdoff/doc/v1-v2.txt @@ -0,0 +1,62 @@ +Differences between RDOFF versions 1 & 2 +======================================== + +This document is designed primarily for people maintaining code which +uses RDOFF version 1, and would like to upgrade that code to work +with version 2. + +The main changes are summarised here: + +Overall format +============== + +The overall format has changed somewhat since version 1, in order +to make RDOFF more flexible. After the file type identifier (which +has been changed to 'RDOFF2', obviously), there is now a 4 byte +integer describing the length of the object module. This allows +multiple objects to be concatenated, while the loader can easily +build an index of the locations of each object. This isn't as +pointless as it sounds; I'm using RDOFF in a microkernel operating +system, and this is the ideal way of loading multiple driver modules +at boot time. + +There are also no longer a fixed number of segments; instead there +is a list of segments, immediately following the header. +Each segment is preceded by a 10 byte header giving information about +that segment. This header has the following format: + +Length Description +2 Type +2 Number +2 Reserved +4 Length + +'Type' is a number describing what sort of segment it is (eg text, data, +comment, debug info). See 'rdoff2.txt' for a list of the segment types. +'Number' is the number used to refer to the segment in the header records. +Not all segments will be loaded; it is only intended that one code +and one data segment will be loaded into memory. It is possible, however, +for a loaded segment to contain a reference to an unloaded segment. +This is an error, and should be flagged at load time. Or maybe you should +load the segment... its up to you, really. + +The segment's data immediately follows the end of the segment header. + +HEADER RECORDS +============== + +All of the header records have changed in this version, but not +substantially. Each record type has had a content-length code added, +a single byte immediately following the type byte. This contains the +length of the rest of the record (excluding the type and length bytes, +but including the terminating nulls on any strings in the record). + +There are two new record types, Segment Relocation (6), and FAR import (7). +The record formats are identical to Relocation (1) and import (2). They are +only of real use on systems using segmented architectures. Systems using +a flat model should treat FAR import (7) exactly the same as an import (2), +and should either flag segment relocation as an error, or attempt to figure +out whether it is a reference to a code or data symbol, and set the value +referenced to the according selector value. I am opting for the former +approach, and would recommend that others working on 32 bit flat systems +do the same. |