a.out(6): document dynamically loadable modules

The loaders can generate export tables in executables and build
dynamically loadable modules and there is a library to load those
floating around.  This documents the format of dynamically loadable
modules.

1 files changed, 49 insertions, 4 deletions

diff --git a/sys/man/6/a.out b/sys/man/6/a.out
index e80ad5ea5..be9bde2af 100644
--- a/sys/man/6/a.out
+++ b/sys/man/6/a.out
@@ -4,10 +4,10 @@ a.out \- object file format
 .SH SYNOPSIS
 .B #include <a.out.h>
 .SH DESCRIPTION
-An executable Plan 9 binary file has up to six sections:
-a header, the program text, the data,
-a symbol table, a PC/SP offset table (MC68020 only),
-and finally a PC/line number table.
+An executable Plan 9 binary file has up to seven sections: a header,
+the program text, the data, a symbol table, a PC/SP offset table
+(MC68020 only), a PC/line number table, and finally relocation data
+(dlm only).
 The header, given by a structure in
 .BR <a.out.h> ,
 contains 4-byte integers in big-endian order:
@@ -26,6 +26,7 @@ typedef struct Exec {
 } Exec;
 
 #define HDR_MAGIC	0x00008000	/* header expansion */
+#define DYN_MAGIC	0x80000000	/* dynamically loadable module */
 
 #define	_MAGIC(f, b)	((f)|((((4*(b))+0)*(b))+7))
 #define	A_MAGIC	_MAGIC(0, 8)		/* 68020 */
@@ -259,6 +260,48 @@ to be printed by the above algorithm.  The offset is associated with the
 first previous
 .B z
 symbol in the symbol table.
+.PP
+In dynamically loadable modules, relocation data follows directly
+after the PC/line number table.
+It starts with the 4-byte big-endian size of the following data, which
+consists of an import table and a relocation table.
+The import table starts with the 4-byte big-endian number of imported
+symbols, followed by a list of entries, laid out as:
+.IP
+.EX
+u32int sig;	/* big-endian */
+char   name[\f2n\fP];	/* NUL-terminated */	
+.EE
+.PP
+.I Sig
+is the type signature value generated by the C compiler's
+.B signof
+operator applied to the type.
+.I Name
+is the linkage name of the function or data.
+.PP
+The relocation table starts with the 4-byte big-endian number of
+fixups, followed by a list of those, each laid out as:
+.IP
+.EX
+uchar m;
+uchar ra[\f2c\fP];
+.EE
+.PP
+The four low bits of
+.I m
+are an architecture-dependent relocation mode.
+.I C
+is 2 raised to the power of the two high bits of
+.IR m ,
+which can be 0, 1, or 2.
+.I Ra
+is a big-endian increment of the working address in the module.
+Each iteration in the process of relocation, the working address is
+incremented by the current
+.IR ra .
+Then, the value in the module at the working address is modified as
+specified by the relocation mode.
 .SH "SEE ALSO"
 .IR db (1), 
 .IR acid (1), 
@@ -273,3 +316,5 @@ There is no type information in the symbol table; however, the
 .B -a
 flags on the compilers will produce symbols for
 .IR acid (1).
+.PP
+Dynamically loadable modules exist, and aren't even used anywhere.