Added man page describing format of the iso dump file.

git-svn-id: svn://svn.linux1394.org/libraw1394/trunk@68 53a565d1-3bb7-0310-b661-cf11e63c67ab

4 files changed, 68 insertions, 30 deletions

diff --git a/doc/Makefile.am b/doc/Makefile.am
index 9569e2b..d6e10c7 100644
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -1,8 +1,8 @@
-EXTRA_DIST = testlibraw.1.in sendiso.1.in dumpiso.1.in \
+EXTRA_DIST = testlibraw.1.in sendiso.1.in dumpiso.1.in isodump.1.in \
 	libraw1394.sgml libraw1394 libraw1394.ps
 
 # man files for testlibraw
-man_MANS = testlibraw.1 sendiso.1 dumpiso.1
+man_MANS = testlibraw.1 sendiso.1 dumpiso.1 isodump.1
 
 # libraw1394 docbook documentation
 
diff --git a/doc/dumpiso.1.in b/doc/dumpiso.1.in
index b2ced09..2412dcf 100644
--- a/doc/dumpiso.1.in
+++ b/doc/dumpiso.1.in
@@ -5,32 +5,34 @@ dumpiso \- dump IEEE 1394 isochronous channel packets
 .B dumpiso
 [ \fIoptions\fR ] [ \fIFILE\fR ]
 .SH DESCRIPTION
-dumpiso listens on a selected range of channels and dumps all received packets
-into the file \fIFILE\fR or, if not given, to standard output.  While dumping,
-the current number of received packets is written to standard error and updated
-with every packet.
+dumpiso listens on a selected range of channels and dumps all received
+packets into the file \fIFILE\fR or, if not given, to standard output.
+While dumping, the current number of received packets is written to
+standard error and updated with every packet.
 .PP
-It uses a simple file format for the dumps, described in another man page yet to
-be written.  The dumped packets can be sent out again with \fBsendiso\fR(1).
+It uses a simple file format for the dumps which is described in
+\fBisodump\fR(5).  The dumped packets can be sent out again with
+\fBsendiso\fR(1).
 .SH OPTIONS
 .TP
 .B -c\fR,\fB --channels=\fICHANNELS
-Sets the channels to listen on.  \fICHANNELS\fR can be either a single number,
-in which case this is the only channel to listen on, or a range of channels in
-the form X-Y.  Channel numbers can range from 0 to 63.  You can give this option
-multiple times, new channels are added to the list of already set channels.
-Defaults to all channels.
+Sets the channels to listen on.  \fICHANNELS\fR can be either a single
+number, in which case this is the only channel to listen on, or a
+range of channels in the form X-Y.  Channel numbers can range from 0
+to 63.  You can give this option multiple times, new channels are
+added to the list of already set channels.  Defaults to all channels.
 .TP
 .B -p\fR,\fB --port=\fIPORT
-Choose port \fIPORT\fR for receiving.  A port is a 1394 card or chip and
-represents one connected bus, therefore this is only relevant when you have
-multiple of these.  Defaults to 0.
+Choose port \fIPORT\fR for receiving.  A port is a 1394 card or chip
+and represents one connected bus, therefore this is only relevant when
+you have multiple of these.  Defaults to 0.
 .TP
 .B -h\fR,\fB --help
 Show help text and exit.
 .SH BUGS
 None known.
 .SH SEE ALSO
-.B sendiso\fR(1)
+.B sendiso\fR(1),
+.B isodump\fR(5)
 .SH AUTHOR
 Andreas Bombe <aeb@debian.org>
diff --git a/doc/isodump.5.in b/doc/isodump.5.in
new file mode 100644
index 0000000..7ab20a6
--- /dev/null
+++ b/doc/isodump.5.in
@@ -0,0 +1,35 @@
+.TH isodump 5 "isodump v1" "libraw1394 @VERSION@" "Linux IEEE 1394"
+.SH NAME
+isodump \- format of IEEE 1394 isochronous packets dump file
+.SH DESCRIPTION
+The isodump format stores a series of IEEE 1394 isochronous stream
+packets (possibly from multiple channels), including their headers.
+Its main use is as the output format of \fBdumpiso\fR(1) and the input
+format of \fBsendiso\fR(1).
+.PP
+The 32 byte header starts at offset 0 with the string "1394 isodump
+v1" followed by a zero byte.  The next 8 bytes form a 64 bit big
+endian integer, which represents a bit mask of the channels that were
+dumped.  A set bit at position (1 << x) signifies that channel x was
+being listened on.  The following 8 bytes are set to zero.
+.PP
+The iso packets follow the header and are appended to the data stream
+in the order they were received.  The packets consist of the header
+quadlet as originally received and the data quadlets following
+directly.  The CRC quadlets after header and data do not appear and
+everything is in big endian, as seen on the bus.
+.PP
+There is no further framing of the packets in the format, packet
+boundaries can be found by looking at the data size field in the
+header quadlet of each packet.  The data size field appears in the
+most significant 16 bits of the header quadlet, contain the size in
+bytes (the actual packet is padded to a multiple of four bytes) and do
+not include the header packet.
+.SH COMPATIBILITY
+This format was introduced with the iso send and dump tools
+distributed with libraw1394.  No one else uses it so far.
+.SH SEE ALSO
+.B sendiso\fR(1),
+.B dumpiso\fR(1)
+.SH AUTHOR
+Andreas Bombe <aeb@debian.org>
diff --git a/doc/sendiso.1.in b/doc/sendiso.1.in
index 8f316ca..e80cae9 100644
--- a/doc/sendiso.1.in
+++ b/doc/sendiso.1.in
@@ -5,15 +5,15 @@ sendiso \- send IEEE 1394 isochronous packets from dump file
 .B sendiso
 [ \fIoptions\fR ] \fIFILE\fR
 .SH DESCRIPTION
-sendiso takes the dump file \fIFILE\fR as generated by \fBdumpiso\fR(1),
-extracts the packets and sends them as they were received (in the same order,
-with the same channel numbers) as fast as possible - timing of the original dump
-is not preserved.
+sendiso takes the dump file \fIFILE\fR as generated by
+\fBdumpiso\fR(1), extracts the packets and sends them as they were
+received (in the same order, with the same channel numbers) as fast as
+possible - timing of the original dump is not preserved.
 .PP
-This program does not allocate any isochronous resources but just starts
-sending.  It should not be used in live environments where it might interfere
-with properly set up isochronous transmissions, it is a debug and performance
-benchmarking tool.
+This program does not allocate any isochronous resources but just
+starts sending.  It should not be used in live environments where it
+might interfere with properly set up isochronous transmissions, it is
+a debug and performance benchmarking tool.
 .SH OPTIONS
 .TP
 .B -l\fR,\fB --loop=\fICOUNT
@@ -23,19 +23,20 @@ Send dump file \fICOUNT\fR times.  Defaults to 1.
 Send dump file in an endless loop.
 .TP
 .B -s\fR,\fB --speed=\fISPEED
-Send packets at speed \fISPEED\fR, which can be given as 100, 200 and 400 (in
-Mbit/s) or abbreviated as 1, 2 and 4.  Defaults to 100.
+Send packets at speed \fISPEED\fR, which can be given as 100, 200 and
+400 (in Mbit/s) or abbreviated as 1, 2 and 4.  Defaults to 100.
 .TP
 .B -p\fR,\fB --port=\fIPORT
 Choose port \fIPORT\fR for sending.  A port is a 1394 card or chip and
-represents one connected bus, therefore this is only relevant when you have
-multiple of these.  Defaults to 0.
+represents one connected bus, therefore this is only relevant when you
+have multiple of these.  Defaults to 0.
 .TP
 .B -h\fR,\fB --help
 Show help text and exit.
 .SH BUGS
 None known.
 .SH SEE ALSO
-.B dumpiso\fR(1)
+.B dumpiso\fR(1),
+.B isodump\fR(5)
 .SH AUTHOR
 Andreas Bombe <aeb@debian.org>